> 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/sv/data-api/api-overview/ad-interaction-events-reporting/integrate-banner-x-shoppable-banner-interaction-reporting.md). # Integrera interaktionsrapportering för Banner X Shoppable Banner En shoppbar banner är en Banner X annons med flera hotspot-områden för följprodukter i en och samma placering. När dessa händelser väl flödar delar kampanjrapporten upp bannerns resultat för varje följprodukt — visningar, klick och CTR (samt varukorgshändelser där det är integrerat) — i stället för enbart en totalsumma på bannernivå. Den här guiden täcker endast interaktionstyperna för shoppbara banners. För slutpunkt, autentisering, kärnfält (`adId`, `timestamp`, spårnings-ID), beacon-mekanik, avduplicering och testning, se [Teknisk referens för rapportering av annonsinteraktionshändelser](https://help.citrusad.com/retail-media-interface/integration/sv/data-api/api-overview/ad-interaction-events-reporting). ## Förutsättningar | Förutsättning | Syfte | | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | Läs [Teknisk referens](https://help.citrusad.com/retail-media-interface/integration/sv/data-api/api-overview/ad-interaction-events-reporting) | Bekräftar kraven för slutpunkt, autentisering, kärnfält och avduplicering. | | Följprodukter konfigurerade på Banner X annonskreativ | Säkerställer att interaktioner på produktnivå kan attribueras till annonskreativet. | | Levererade annonser returnerar ett realiserat `adId` | Länkar varje händelse till den levererade annonsinstansen. | | `productCode` och `catalogId` tillgänglig per följprodukt | Identifierar produkten och katalogen som används i rapporteringen. | | Synlighetsregel överenskommen för produktkort | Definierar när ett produktkort räknas som som visat för `productImpression`. | | Konsekvent spårnings-ID per annons-session | Stöder attribuering och avduplicering med hjälp av `sessionId`, `customerId`, or `dtmToken`. | ## Interaktionstyper för rapportering av shoppbara banners Dessa är `adInteraction` händelser (ingen `moduleId`). Skicka kärnfälten plus nyckelfälten nedan. `productImpression` och `productClick` är de två händelser som låser upp fliken Produkter — utlös båda. | `interactionType` | Nyckelfält | När den ska utlösas | Rapporteringssyfte | | ------------------- | ------------------------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------- | | `productImpression` | `productCode`, `catalogId` | Ett produktkort/SKU blir synligt enligt dina synlighetsregler | Visningar per produkt — fyller visningskolumnen (och rader med noll klick) | | `productClick` | `productCode`, `catalogId` | Shopparen klickar på ett produktkort/SKU | Klick per produkt — driver klick och CTR | | `creativeClick` | `creativeId` | Klick på ett element i annonskreativet som inte är en produkt | Engagemang med annonskreativ som inte är en produkt | | `cart` | `productCode`, `catalogId`, `units`, valfri `conversionValue` | Varukorgsändring från annonskontexten | Intention att lägga i varukorgen / produktvärde | ## Synlighetsregler för `productImpression` | Regel | Vägledning | | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Definiera när ett kort räknas som visat | Kom överens om en synlighetsregel, till exempel procentandel synlig plus tid på skärmen, och tillämpa den konsekvent över webb och app. | | Utlös visningar en gång per synlighetstillfälle | Dämpa scroll-jitter och omrenderingar så att en enskild visning inte räknas flera gånger. | ## Varukorg: Skicka absolut nuvarande antal enheter Utlös `cart` vid varje varukorgsinteraktion — första tillägget, varje `+`, varje `−`, och borttagning (tillbaka till `0`) — med `units` inställt på det absoluta nuvarande antalet enheter, inte en deltaförändring. Att återigen skicka den nuvarande totalsumman håller antalen korrekta vid avduplicering. Lägg till `conversionValue` när du har det. {% hint style="info" %} **Exempel** — en shoppare lägger till en produkt, ökar antalet två gånger och tar sedan bort den:\*\* `cart {units: 1}` → `cart {units: 2}` → `cart {units: 3}` → `cart {units: 0}` {% endhint %} ## Steg-för-steg-implementering ### Steg 1 — Fånga annonskontext Läs det realiserade `adId` från den levererade annonsen, och `productCode`/`catalogId` för varje följkort. Upprätta ett spårnings-ID för sessionen och återanvänd det på visningar och klick. ### Steg 2 — Utlös produktvisningar När ett kort uppfyller din synlighetsregel, utlös `productImpression` en gång för den produkten. ```javascript navigator.sendBeacon( "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" + new URLSearchParams({ adId, interactionType: "productImpression", sessionId, timestamp: new Date().toISOString(), productCode, catalogId }) ); ``` ### Steg 3 — Utlös klick på 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 }) ); ``` ### Steg 4 — Utlös varukorgsändringar Vid tillägg/uppdatering, utlös `cart` med den absoluta nuvarande `units` för den produkten (och `conversionValue` om du har det) — se varukorgsregeln ovan. ## Exempelbegäranden Fullständiga GET-URL:er (radbrutna för läsbarhet — skicka som en enda kodad söksträng). ### Produktvisning ```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 ``` ### Produktklick ```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 ``` ### Lägg i varukorg från annons ```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 ``` ## Hur det ska se ut | Kontroll | Detalj | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Händelser returnerar HTTP 200 | `productImpression` och `productClick` returnerar HTTP 200 i PRE/QA. | | Fliken Produkter är helt ifylld | Varje konfigurerad följeprodukt visas, inklusive rader med noll engagemang (visningar fyller på rader med noll klick). | | Deduplicering fungerar | Antalen håller sig stabila när du utlöser samma visning/klick igen. | ## Felsökning (specifikt för Shoppable Banner) | Symptom | Lösning | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Obligatoriska produkthändelser kommer inte fram | Bekräfta att bannern är Banner X med följeprodukter på annonskreativstadiet, och att `productImpression` och `productClick` utlöser med `productCode`/`catalogId`. | | Visningar utlöses vid varje scrollning/omrendering | Utlös en `productImpression` per produkt per synlighetsförekomst; avstudsa (debounce). | | Fliken Produkter visar felaktiga eller saknade produkter | Sannolikt en `productCode`/`catalogId` felmatchning med katalogen — stäm av ID:na du skickar mot katalogflödet. | | Enheter i varukorgen ser fel ut | Du skickar deltan — skicka den absoluta nuvarande `units`. | För generell slutpunktsfelsökning, se [Teknisk referens för rapportering av annonsinteraktionshändelser](https://help.citrusad.com/retail-media-interface/integration/sv/data-api/api-overview/ad-interaction-events-reporting) felsökningssektionen. --- # 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/sv/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.