> 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`.
* [ ] Request flags: For C2S-only implementations, set `trackingMode` to `"client-to-server"` and provide `trackingBaseUrl` with your reverse-proxy base URL. When `trackingMode` is set to `"client-to-server"`, omitting `trackingBaseUrl` results in a 4xx error response.
* [ ] Rendering: Content modules render correctly on your site in the correct order, including VIDEO\_TILE / BACKGROUND\_VIDEO / FILTER\_MENU when those types are in the template.
* [ ] Them&#x65;**:** All `theme` color values are required and returned as 6-character hexadecimal strings (Hex6). No `theme` fields are `null`, and all provided values are applied.
* [ ] 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}` is substituted with the current millisecond timestamp on every event fire.

**Tracking Validation**

* [ ] Impression pixel (C2S) : Every entry in `trackingTemplates.client.impressionPixelUrls` fires and returns 200 `image/gif`. Absolute client URLs should be used as-is. Relative (path-only) URLs must be prefixed with your reverse-proxy base URL. Never apply both.
* [ ] Impression notification (S2S) : Composed server impression URL (with `{TS}` and `{TCF}` substituted); **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 (with `{TS}`, `{QTY}`, `{CONVERSION_VALUE}`, `{TCF}` substituted) returns 204 No Content.
* [ ] Add-to-cart (S2S) : Composed `server.addToCartEvent` called direct to tracking host (macros substituted) returns 204 No Content.
* [ ] Consent: When `params.iabConsentString` contains `{TCF}`, ensure your integration replaces it with the current TCF v2 consent string obtained from the CMP before firing the tracking request.
* [ ] Video (VAST or Native Player): Confirm that `VIDEO_TILE` playback fires either VAST (`adm`) tracking events **or** `nativePlayer.trackers`, but not both. For `BACKGROUND_VIDEO`, fire `videoCreativeView` once when the video becomes visible.
* [ ] Filter Menu Images: Verify that items with an `imageUrl` display an image, while items without an `imageUrl` still render their label correctly.
* [ ] Click Coverage: Verify that every interactive element on the page fires a click tracker, including Filter Menu items, not just Hero CTAs and product card CTAs.

**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                    | Confirm every `theme` path is a hex6 string as documented in **Theme Object**. Do not expect `null` inside `theme`.                                                                                                             |
| C2S URLs 404 or double-prefix                          | If a tracking URL already begins with `https://`, use it exactly as returned by the API. If the URL begins with `/`, prepend your reverse-proxy base URL only once.                                                             |
| Video analytics missing or doubled                     | Fire either VAST (`adm`) tracking events or `nativePlayer.trackers`, but not both. For `BACKGROUND_VIDEO`, only the `videoCreativeView` event is supported.                                                                     |
| `trackingMode` client-to-server returns 4xx            | Ensure that `trackingBaseUrl` is provided when `trackingMode` is set to `"client-to-server"`. Specify either the origin or the origin with a path prefix.                                                                       |
| API returns no content for a page you know is approved | The page version may still be processing video assets. A Brand Page does not begin serving until all videos on that version have completed transcoding.                                                                         |
| Click data missing for some elements                   | Verify that every interactive element fires its associated click tracker, including Filter Menu items. Missing click-tracking events do not affect page rendering and may only become apparent through reporting discrepancies. |

## 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. Client URLs are returned as fully qualified URLs when `trackingBaseUrl` is provided. Otherwise, they are returned as relative paths.                                                                                                         | `<img src="impression-pixel">, navigator.sendBeacon(clickEvent)`                    |
| S2S Tracking      | Backend tracking using GET or POST requests to tracking URLs on the Epsilon tracking host. These URLs are never modified by `trackingBaseUrl` and must be used exactly as returned by the API.                                                                                                                                                                                                     | Your server → Epsilon server                                                        |
| trackingBaseUrl   | Optional request field that specifies the first-party tracking proxy base URL. When provided, all C2S and VAST tracking URLs are returned as fully qualified URLs using this base. This field is required when `trackingMode` is set to `"client-to-server"`.                                                                                                                                      | `"https://www.retailer.com/epsilon"`                                                |
| trackingMode      | Optional request field that determines whether tracking is performed using `"client-to-server"` or `"server-to-server"`. When specified, the response includes only the applicable tracking templates and video trackers for the selected mode. If omitted, both client-side and server-side tracking URLs are returned.                                                                           | `"client-to-server"`                                                                |
| clickTrackingMode | Optional request field that determines how click tracking is delivered. Supported values are `"redirect"`, `"beacon"`, and `"both"`. When specified, only the corresponding click-tracking templates are returned in the response. If omitted, both click-tracking methods are returned.                                                                                                           | `"beacon"`                                                                          |
| VIDEO\_TILE       | A click-to-play video module that supports both VAST and native-player integrations. Video content is provided through VAST XML in `adm`, while the `nativePlayer` object is available for integrations that do not parse VAST responses.                                                                                                                                                          | `"contentType": "VIDEO_TILE"`                                                       |
| BACKGROUND\_VIDEO | A muted, looping background video module that uses a structured JSON response, including `mediaFiles[]` and related metadata. This module does not use VAST and does not include an `adm` field.                                                                                                                                                                                                   | `"contentType": "BACKGROUND_VIDEO"`                                                 |
| 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](https://help.citrusad.com/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             | Placeholders returned in `trackers.<slot>.params` that must be replaced at runtime before firing the tracking request. Supported macros include `"{TS}"` (timestamp), `"{RURL}"` (redirect destination URL), `"{TCF}"` (IAB TCF v2 consent string), `"{QTY}"` (cart quantity), `"{CONVERSION_VALUE}"` (line-item conversion value), and `"{RURL_KID}"` / `"{RURL_SIG}"` (redirect-signing values). | <p><code>{TS} → 1737485823910</code><br><code>{TCF}</code> → TC string from CMP</p> |
| 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                    |


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.citrusad.com/retail-media-interface/integration/brand-pages/brand-page-retailer-integration-guide/validation-troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
