> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/integration/brand-pages/brand-page-retailer-integration-guide/validation-troubleshooting.md).
# Validation & Troubleshooting
## Testing and Validation
### Pre-Launch Validation Checklist
**Technical Integration**
* [ ] API :`POST /ads/v3/brand-pages` returns 200 with `contentData`.
* [ ] Rendering : Content modules render correctly on your site in the correct order.
* [ ] Theme: `theme` fields are applied correctly; `null` values fall back to retailer style guide defaults.
* [ ] Optional fields: Renderer and tracking logic must tolerate omitted, null, or empty optional module fields, as well as omitted tracking nodes, without errors (validate using multiple live templates, not just a single demo brand page).
* [ ] Styling : Brand page matches your site's design system.
* [ ] Mobile : Brand page displays correctly on mobile devices.
* [ ] Cache-busting : `{TS}` value changes on every request.
**Tracking Validation**
* [ ] Impression pixel (C2S) : Every entry in `trackingTemplates.client.impressionPixelUrls` fires and returns 200 `image/gif`
* [ ] Impression notification (S2S) : Composed server impression URL; **GET** or **POST** direct to Epsilon tracking host returns 204 No Content.
* [ ] Click tracking (C2S) : Either the composed `client.clickRedirect` URL returns 302 to the correct destination, or the composed `client.clickEvent` returns 204 No Content (whichever option your flow uses - not both)
* [ ] Click notification (S2S) : **GET** or **POST** direct to the composed server URL returns 204 No Content
* [ ] Add-to-cart (C2S) : Composed `client.addToCartEvent` fired as event beacon returns 204 No Content
* [ ] Add-to-cart (S2S) : Composed `server.addToCartEvent` called direct to tracking host returns 204 No Content
**Infrastructure & Privacy**
* [ ] Reverse proxy : C2S tracking requests forwarded through your domain; S2S is not sent through the proxy
* [ ] Headers : `RP-Host`, `X-Forwarded-For`, `X-Forwarded-Request-Path`, `Referer` are present on proxied requests
* [ ] Privacy : No PII present in any parameter or URL
* [ ] HTTPS : All requests use secure connections
* [ ] Product pages : Pages render correctly after click redirect
### Recommended Tools
* Browser developer tools: Network tab to inspect pixel loads and redirects.
* Fiddler or Charles Proxy: Inspect reverse proxy behavior and header forwarding.
### Troubleshooting
| Issue | Check |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pixels fail to load | Verify DNS/SSL, confirm proxy path rewrite, check reachability to the Epsilon tracking host. |
| Redirects don't forward | Ensure `{RURL}` is URL-encoded, verify proxy preserves query string. |
| API returns no content | Verify `catalogId` and `urlSlug` match an active brand page campaign. |
| Tracking blocked by ad blocker | Confirm reverse proxy is configured - tracking should route through your domain. |
| Add-to-cart not tracked | Ensure you fire the composed client or server add-to-cart URL after the cart action. |
| Page throws when loading some brand pages | Likely treating doc/example fields as always required. Log raw module JSON, add guards for optional keys and missing tracking, and confirm the template allows or disables those fields. |
| Theme colors not applying correctly | Check that `null` theme fields fall back to your style guide defaults, rather than being rendered as literal null values or empty strings. |
## Glossary
**Essential Terms for Brand Pages Integration**
| Term | Definition | Example |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| API Key | Your authentication credential for Epsilon services | `Basic abc123xyz...` |
| Brand Page | A branded landing page experience on your site | yoursite.com/brands/nike |
| C2S Tracking | Client-to-Server: Browser-based tracking. Impressions use 1x1 pixels; clicks use a 302 redirect or an event beacon; add-to-cart uses an event beacon. | `
, navigator.sendBeacon(clickEvent)` |
| S2S Tracking | Server-to-Server: Backend tracking (GET or POST to the composed tracking URLs) | Your server → Epsilon server |
| Content Module | Individual content blocks (hero, text, products, etc.) | Hero banner, product grid |
| Module Tags | Optional string labels on a module (e.g., `["header"]`) set in the template. Used by retailers for layout routing, analytics, or mapping to their own components. Omitted from the response when empty. | `"tags": ["header"]` |
| Theme | Always present on success in the API response: nested `colors` (background + seven text roles) and `buttons` (`primary` / `secondary` with `background` and `text`). All theme color fields are required (hex6). See [Theme Object](/retail-media-interface/integration/brand-pages/brand-page-retailer-integration-guide/brand-page-apis.md#theme-object). | "theme": { "colors": { ... }, "buttons": { ... } } |
| Impression | When a brand page is viewed by a user | Page load = 1 impression |
| Click | When a user clicks on brand page content | CTA button click |
| Conversion | When a user adds a product to cart from brand page | Add to cart action |
| Reverse Proxy | Routes tracking through your domain to avoid ad blockers | `yoursite.com/epsilon/` → Epsilon |
| URL Slug | The brand identifier in the URL path | `nike` in `/brands/nike` |
| Catalog ID | Your unique product catalog identifier | Provided by Epsilon |
| Macro | Response placeholders (`{TS}`, `{RURL}`) in `tracking.params` that you replace at runtime; | `{TS} → 1737485823910` |
| IAB TCF | Interactive Advertising Bureau Transparency & Consent Framework | GDPR compliance standard |
| PII | Personally Identifiable Information (never send this!) | Email, phone, real name |
| Cache-busting | Adding timestamps to prevent cached responses | `?ts=1737485823910` |
### Technical Acronyms
| Acronym | Full Term | What It Means |
| ------- | ---------------------------------- | -------------------------------------- |
| RMN | Retail Media Network | Epsilon's advertising platform |
| CTA | Call-to-Action | Clickable buttons/links |
| JSON | JavaScript Object Notation | Data format for API requests/responses |
| HTTPS | HTTP Secure | Encrypted web protocol |
| GDPR | General Data Protection Regulation | EU privacy law |
| TLS | Transport Layer Security | Encryption protocol |
| DNS | Domain Name System | Internet address system |
| SSL | Secure Sockets Layer | Encryption protocol |
| RFC | Request for Comments | Technical standards documents |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://help.citrusad.com/retail-media-interface/integration/brand-pages/brand-page-retailer-integration-guide/validation-troubleshooting.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.