> 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/cs/data-api/api-overview/ad-interaction-events-reporting/integrate-banner-x-shoppable-banner-interaction-reporting.md). # Integrace hlášení interakce s nakupovatelným bannerem Banner X Shoppable Banner je Banner X reklama s několika hotspoty doprovodných produktů v jednom umístění. Jakmile tyto události začnou proudit, přehled kampaně rozepíše výkon banneru na každý doprovodný produkt — zobrazení, kliknutí a CTR (plus akce košíku, pokud jsou integrované) — namísto jednoho celkového součtu na úrovni banneru. Tento průvodce se zabývá pouze typy interakcí se Shoppable Bannerem. Informace o endpointu, autentizaci, základních polích (`adId`, `timestamp`, tracking id), mechanice beaconu, dedupu a testování naleznete v [Technické referenci k reportování událostí interakce s reklamou](https://help.citrusad.com/retail-media-interface/integration/cs/data-api/api-overview/ad-interaction-events-reporting). ## Předpoklady | Předpoklad | Účel | | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | Přečtěte si [Technickou referenci](https://help.citrusad.com/retail-media-interface/integration/cs/data-api/api-overview/ad-interaction-events-reporting) | Potvrzuje požadavky na endpoint, autentizaci, základní pole a deduplikaci. | | Doprovodné produkty nakonfigurované na Banner X reklamním materiálu | Zajišťuje, že interakce na úrovni produktů lze přiřadit k reklamnímu materiálu. | | Doručené reklamy vracejí realizované `adId` | Propojuje každou událost s doručenou instancí reklamy. | | `productCode` a `catalogId` k dispozici pro každý doprovodný produkt | Identifikuje produkt a katalog použité v reportech. | | Pravidlo viditelnosti dohodnuté pro dlaždice produktů | Definuje, kdy se dlaždice produktu počítá jako zobrazená pro `productImpression`. | | Konzistentní tracking id pro ad session | Podporuje atribuci a deduplikaci pomocí `sessionId`, `customerId`, or `dtmToken`. | ## Typy interakcí pro reportování Shoppable Bannerů Toto jsou `adInteraction` události (ne `moduleId`). Odesílejte základní pole a klíčová pole uvedená níže. `productImpression` a `productClick` jsou dvě události, které zpřístupňují kartu Produkty — spusťte obě. | `interactionType` | Klíčová pole | Kdy spustit | Účel reportování | | ------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | | `productImpression` | `productCode`, `catalogId` | Dlaždice produktu / SKU se stane viditelnou podle vašich pravidel viditelnosti | Zobrazení po produktech — plní sloupec zobrazení (a řádky bez kliknutí) | | `productClick` | `productCode`, `catalogId` | Nakupující klikne na dlaždici produktu / SKU | Kliknutí po produktech — generuje kliknutí a CTR | | `creativeClick` | `creativeId` | Kliknutí na neproduktový prvek reklamního materiálu | Zapojení s neproduktovým reklamním materiálem | | `cart` | `productCode`, `catalogId`, `units`, volitelné `conversionValue` | Změna košíku z kontextu reklamy | Záměr přidat do košíku / hodnota produktu | ## Pravidla viditelnosti pro `productImpression` | Pravidlo | Doporučení | | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Definujte, kdy se dlaždice počítá jako zobrazená | Dohodněte pravidlo viditelnosti, například procento viditelnosti plus čas na obrazovce, a aplikujte jej konzistentně napříč webem a aplikací. | | Spusťte zobrazení jednou při každém výskytu viditelnosti | Ošetřete kmitání při skrolování a opětovné vykreslování (debounce), aby se jedno zobrazení nepočítalo vícekrát. | ## Košík: Odesílejte absolutní aktuální počet kusů Spusťte `cart` při každé interakci s košíkem — počáteční přidání, každé `+`každé `−`, a odebrání (zpět na `0`) — s `units` nastaveným na absolutní aktuální počet kusů, ne na deltu. Opětovné odeslání aktuálního součtu udržuje počty správné i při deduplikaci. Přidejte `conversionValue` jakmile jej máte. {% hint style="info" %} **Příklad** — nakupující přidá produkt, dvakrát zvýší počet a pak jej odebere:\*\* `cart {units: 1}` → `cart {units: 2}` → `cart {units: 3}` → `cart {units: 0}` {% endhint %} ## Implementace krok za krokem ### Krok 1 — Zachycení kontextu reklamy Přečtěte realizované `adId` z doručené reklamy, a `productCode`/`catalogId` pro každou doprovodnou dlaždici. Vytvořte jedno tracking id pro relaci a znovu jej použijte u zobrazení a kliknutí. ### Krok 2 — Spuštění zobrazení produktů Jakmile dlaždice splní vaše pravidlo viditelnosti, spusťte `productImpression` pro daný produkt jednou. ```javascript navigator.sendBeacon( "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" + new URLSearchParams({ adId, interactionType: "productImpression", sessionId, timestamp: new Date().toISOString(), productCode, catalogId }) ); ``` ### Krok 3 — Odeslání události Kliknutí na produkt ```javascript navigator.sendBeacon( "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" + new URLSearchParams({ adId, interactionType: "productClick", sessionId, timestamp: new Date().toISOString(), productCode, catalogId }) ); ``` ### Krok 4 — Odeslání změn košíku Při přidání/aktualizaci odešlete `cart` s absolutním aktuálním `units` pro daný produkt (a `conversionValue` pokud ji máte) — viz pravidlo pro košík výše. ## Ukázkové požadavky Úplné adresy URL pro GET (zalamované pro přehlednost — odesílejte jako jediný zakódovaný dotazovací řetězec). ### Zobrazení produktu ```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 ``` ### Kliknutí na produkt ```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 ``` ### Přidání do košíku z reklamy ```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 ``` ## Jak vypadá správný výsledek | Kontrola | Detail | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Události vracejí HTTP 200 | `productImpression` a `productClick` vracejí HTTP 200 v PRE/QA. | | Záložka Produkty je plně zaplněna | Zobrazí se každý nakonfigurovaný doprovodný produkt, včetně řádků s nulovou interakcí (zobrazení zaplní řádky bez kliknutí). | | Deduplikace funguje | Počty zůstávají stabilní, když znovu odešlete stejné zobrazení/kliknutí. | ## Řešení problémů (specifika nakupovatelného banneru) | Příznak | Náprava | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Požadované události produktu nepřicházejí | Potvrďte, že banner je Banner X s doprovodnými produkty ve fázi reklamního materiálu a že `productImpression` a `productClick` se odesílají s `productCode`/`catalogId`. | | Zobrazení se odesílají při každém skrolování / novémvyykreslení | Odešlete jedno `productImpression` na produkt a výskyt viditelnosti; použijte debounce. | | Záložka Produkty zobrazuje špatné nebo chybějící produkty | Pravděpodobně dochází k nezhodě `productCode`/`catalogId` s katalogem — porovnejte ID, která odesíláte, s zdrojem katalogu. | | Počty kusů v košíku vypadají špatně | Posíláte rozdíly — odešlete absolutní aktuální `units`. | Obecné řešení problémů s koncovými body naleznete v [Technické referenci k reportování událostí interakce s reklamou](https://help.citrusad.com/retail-media-interface/integration/cs/data-api/api-overview/ad-interaction-events-reporting) sekci řešení problémů. --- # 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/cs/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.