> 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/data-api/api-overview/ad-interaction-events-reporting/integrate-banner-x-shoppable-banner-interaction-reporting.md). # Integrate Banner X Shoppable Banner Interaction Reporting A Shoppable Banner is a Banner X ad with multiple companion-product hotspots in one placement. Once these events flow, the campaign report breaks banner performance down to each companion product — impressions, clicks, and CTR (plus cart actions where integrated) — instead of a single banner-level total. This guide covers only the Shoppable Banner interaction types. For the endpoint, authentication, core fields (`adId`, `timestamp`, tracking id), beacon mechanics, dedup, and testing, see the [Ad Interaction Events Reporting Technical Reference](https://help.citrusad.com/retail-media-interface/integration/data-api/api-overview/ad-interaction-events-reporting). ## Prerequisites | Prerequisite | Purpose | | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | Read the [Technical Reference](https://help.citrusad.com/retail-media-interface/integration/data-api/api-overview/ad-interaction-events-reporting) | Confirms endpoint, authentication, core fields, and deduplication requirements. | | Companion products configured on the Banner X creative | Ensures product-level interactions can be attributed to the creative. | | Served ads return a realised `adId` | Links each event to the delivered ad instance. | | `productCode` and `catalogId` available per companion product | Identifies the product and catalog used in reporting. | | Viewability rule agreed for product tiles | Defines when a product tile counts as seen for `productImpression`. | | Consistent tracking id per ad session | Supports attribution and deduplication using `sessionId`, `customerId`, or `dtmToken`. | ## Interaction Types for Shoppable Banner Reporting These are `adInteraction` events (no `moduleId`). Send the core fields plus the key fields below. `productImpression` and `productClick` are the two events that unlock the Products tab — fire both. | `interactionType` | Key fields | When to fire | Reporting purpose | | ------------------- | --------------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------- | | `productImpression` | `productCode`, `catalogId` | A product tile/SKU becomes visible per your viewability rules | Per-product impressions — fills the impression column (and zero-click rows) | | `productClick` | `productCode`, `catalogId` | Shopper clicks a product tile/SKU | Per-product clicks — drives clicks and CTR | | `creativeClick` | `creativeId` | Click on a non-product creative element | Engagement with non-product creative | | `cart` | `productCode`, `catalogId`, `units`, optional `conversionValue` | Cart change from the ad context | Add-to-cart intent / product value | ## Viewability Rules for `productImpression` | Rule | Guidance | | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | Define when a tile counts as seen | Agree a viewability rule, such as percentage visible plus time on screen, and apply it consistently across web and app. | | Fire impressions once per viewability occurrence | Debounce scroll jitter and re-renders so a single sighting is not counted many times. | ## Cart: Send Absolute Current Units Fire `cart` on every cart interaction — initial add, each `+`, each `−`, and removal (back to `0`) — with `units` set to the absolute current unit count, not a delta. Re-sending the current total keeps counts correct under dedup. Add `conversionValue` when you have it. {% hint style="info" %} **Example** — a shopper adds a product, increments twice, then removes it:\*\* `cart {units: 1}` → `cart {units: 2}` → `cart {units: 3}` → `cart {units: 0}` {% endhint %} ## Step-by-Step Implementation ### Step 1 — Capture Ad Context Read the realised `adId` from the served ad, and `productCode`/`catalogId` for each companion tile. Establish one tracking id for the session and reuse it on impressions and clicks. ### Step 2 — Fire Product Impressions When a tile meets your viewability rule, fire `productImpression` once for that product. ```javascript navigator.sendBeacon( "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" + new URLSearchParams({ adId, interactionType: "productImpression", sessionId, timestamp: new Date().toISOString(), productCode, catalogId }) ); ``` ### Step 3 — Fire a Product Click ```javascript navigator.sendBeacon( "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" + new URLSearchParams({ adId, interactionType: "productClick", sessionId, timestamp: new Date().toISOString(), productCode, catalogId }) ); ``` ### Step 4 — Fire Cart Changes On add/update, fire `cart` with the absolute current `units` for that product (and `conversionValue` if you have it) — see the cart rule above. ## Sample Requests Full GET URLs (line-wrapped for readability — send as a single encoded query string). ### Product Impression ```http GET https://integration.retailer.citrusad.com/v1/events/ad/interaction ?adId=shotgun_0001 ×tamp=2026-05-20T10:15:00Z &sessionId=12345gsyuhf-6678ghsj &productCode=prod-00001-01 &catalogId=catlg-custom-DAA001 &interactionType=productImpression ``` ### Product Click ```http GET https://integration.retailer.citrusad.com/v1/events/ad/interaction ?adId=shotgun_0001 ×tamp=2026-05-20T10:15:30Z &sessionId=12345gsyuhf-6678ghsj &productCode=prod-00001-01 &catalogId=catlg-custom-DAA001 &interactionType=productClick ``` ### Add to Cart from Ad ```http GET https://integration.retailer.citrusad.com/v1/events/ad/interaction ?adId=shotgun_0001 ×tamp=2026-05-20T10:16:00Z &customerId=cust-abc-123 &productCode=prod-00001-01 &catalogId=catlg-custom-DAA001 &interactionType=cart &units=2 &conversionValue=29.99 ``` ## What Good Looks Like | Check | Detail | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Events return HTTP 200 | `productImpression` and `productClick` return HTTP 200 in PRE/QA. | | Products tab is fully populated | Every configured companion product appears, including zero-engagement rows (impressions populate the zero-click rows). | | Dedup is working | Counts hold steady when you re-fire the same impression/click. | ## Troubleshooting (Shoppable Banner Specifics) | Symptom | Fix | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Required product events aren't arriving | Confirm the banner is Banner X with companion products at the creative stage, and that `productImpression` and `productClick` fire with `productCode`/`catalogId`. | | Impressions firing on every scroll/re-render | Fire one `productImpression` per product per viewability occurrence; debounce. | | Products tab shows wrong or missing products | Likely a `productCode`/`catalogId` mismatch with the catalog — reconcile the IDs you send against the catalog feed. | | Cart units look wrong | You're sending deltas — send the absolute current `units`. | For general endpoint troubleshooting, see the [Ad Interaction Events Reporting Technical Reference](https://help.citrusad.com/retail-media-interface/integration/data-api/api-overview/ad-interaction-events-reporting) troubleshooting section. --- # 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/data-api/api-overview/ad-interaction-events-reporting/integrate-banner-x-shoppable-banner-interaction-reporting.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.