> 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/de/data-api/api-overview/ad-interaction-events-reporting/integrate-banner-x-shoppable-banner-interaction-reporting.md). # Banner X Shoppable Banner-Interaktions-Meldung integrieren Ein Shoppable Banner ist eine Banner X Anzeige mit mehreren Produkt-Hotspots in einer Platzierung. Sobald diese Ereignisse fließen, schlüsselt der Kampagnenbericht die Banner-Performance auf jedes Begleitprodukt auf – Impressionen, Klicks und CTR (plus Warenkorb-Aktionen, wo integriert) – anstatt einer einzelnen Gesamtsumme auf Banner-Ebene. Dieser Leitfaden behandelt nur die Interaktionstypen für Shoppable Banner. Für den Endpunkt, die Authentifizierung, die Kernfelder (`adId`, `timestamp`, Tracking-ID), Beacon-Mechaniken, Entduplizierung und Tests siehe die [Technische Referenz für das Reporting von Anzeigeninteraktions-Ereignissen](https://help.citrusad.com/retail-media-interface/integration/de/data-api/api-overview/ad-interaction-events-reporting). ## Voraussetzungen | Voraussetzung | Zweck | | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | Lesen Sie die [Technische Referenz](https://help.citrusad.com/retail-media-interface/integration/de/data-api/api-overview/ad-interaction-events-reporting) | Bestätigt Endpunkt-, Authentifizierungs-, Kernfeld- und Entduplizierungsanforderungen. | | Begleitprodukte konfiguriert auf dem Banner X Werbemittel | Stellt sicher, dass Interaktionen auf Produktebene dem Werbemittel zugeordnet werden können. | | Ausgelieferte Anzeigen liefern einen realisierten `adId` | Verknüpft jedes Ereignis mit der ausgelieferten Anzeigeninstanz. | | `productCode` und `catalogId` verfügbar pro Begleitprodukt | Identifiziert das Produkt und den Katalog, die in der Berichterstellung verwendet werden. | | Sichtbarkeitsregel für Produkt-Kacheln vereinbart | Definiert, wann eine Produkt-Kachel als gesehen gilt für `productImpression`. | | Konsistente Tracking-ID pro Anzeigensitzung | Unterstützt Attributierung und Entduplizierung mittels `sessionId`, `customerId`, or `dtmToken`. | ## Interaktionstypen für die Berichterstellung zu Shoppable Bannern Dies sind `adInteraction` Ereignisse (keine `moduleId`). Senden Sie die Kernfelder plus die untenstehenden Schlüsselfelder. `productImpression` und `productClick` sind die zwei Ereignisse, die den Reiter „Produkte“ freischalten – feuern Sie beide. | `interactionType` | Schlüsselfelder | Wann zu feuern | Zweck der Berichterstellung | | ------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `productImpression` | `productCode`, `catalogId` | Eine Produkt-Kachel/SKU wird gemäß Ihren Sichtbarkeitsregeln sichtbar | Impressionen pro Produkt – füllt die Impressionen-Spalte (und Zeilen ohne Klicks) | | `productClick` | `productCode`, `catalogId` | Shopper klickt auf eine Produkt-Kachel/SKU | Klicks pro Produkt – treibt Klicks und CTR an | | `creativeClick` | `creativeId` | Klick auf ein Nicht-Produkt-Werbemittelelement | Interaktion mit Nicht-Produkt-Werbemittel | | `cart` | `productCode`, `catalogId`, `units`, optional `conversionValue` | Warenkorbänderung aus dem Anzeigenkontext | In-den-Warenkorb-Absicht / Produktwert | ## Sichtbarkeitsregeln für `productImpression` | Regel | Empfehlung | | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Definieren Sie, wann eine Kachel als gesehen gilt | Vereinbaren Sie eine Sichtbarkeitsregel, wie z. B. prozentuale Sichtbarkeit plus Zeit auf dem Bildschirm, und wenden Sie diese konsistent über Web und App an. | | Feuern Sie Impressionen einmal pro Sichtbarkeitsereignis | Entprellen Sie Scroll-Ruckeln und Re-Renders, damit eine einzelne Sichtung nicht mehrfach gezählt wird. | ## Warenkorb: Absolute aktuelle Einheiten senden Feuern Sie `cart` bei jeder Warenkorbinteraktion – beim ersten Hinzufügen, jedem `+`, jedem `−`und beim Entfernen (zurück auf `0`) – mit `units` eingestellt auf die absolute aktuelle Stückzahl, nicht auf eine Differenz. Das erneute Senden der aktuellen Gesamtzahl hält die Zählungen unter Entduplizierung korrekt. Fügen Sie `conversionValue` hinzu, wenn Sie sie haben. {% hint style="info" %} **Beispiel** – ein Shopper fügt ein Produkt hinzu, erhöht die Anzahl zweimal und entfernt es dann:\*\* `cart {units: 1}` → `cart {units: 2}` → `cart {units: 3}` → `cart {units: 0}` {% endhint %} ## Schritt-für-Schritt-Implementierung ### Schritt 1 – Anzeigenkontext erfassen Lesen Sie den realisierten `adId` aus der ausgelieferten Anzeige und `productCode`/`catalogId` für jede Begleitkachel. Erstellen Sie eine Tracking-ID für die Sitzung und verwenden Sie diese bei Impressionen und Klicks wieder. ### Schritt 2 – Produkt-Impressionen feuern Wenn eine Kachel Ihre Sichtbarkeitsregel erfüllt, feuern Sie `productImpression` einmal für dieses Produkt. ```javascript navigator.sendBeacon( "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" + new URLSearchParams({ adId, interactionType: "productImpression", sessionId, timestamp: new Date().toISOString(), productCode, catalogId }) ); ``` ### Schritt 3 – Einen Produkt-Klick feuern ```javascript navigator.sendBeacon( "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" + new URLSearchParams({ adId, interactionType: "productClick", sessionId, timestamp: new Date().toISOString(), productCode, catalogId }) ); ``` ### Schritt 4 – Warenkorbänderungen feuern Beim Hinzufügen/Aktualisieren feuern Sie `cart` mit der absoluten aktuellen `units` für dieses Produkt (und `conversionValue` falls Sie eine haben) – siehe die Warenkorb-Regel oben. ## Beispielanfragen Vollständige GET-URLs (zur besseren Lesbarkeit umgebrochen – als einzelnen codierten Query-String senden). ### Produktimpression ```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 ``` ### In den Warenkorb aus Anzeige ```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 ``` ## Wie es richtig aussieht | Prüfung | Detail | | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Ereignisse geben HTTP 200 zurück | `productImpression` und `productClick` geben HTTP 200 in PRE/QA zurück. | | Registerkarte "Produkte" ist vollständig ausgefüllt | Jedes konfigurierte Begleitprodukt wird angezeigt, einschließlich Zeilen ohne Interaktion (Impressionen füllen die Zeilen ohne Klicks). | | Duplikatsentfernung funktioniert | Zahlen bleiben stabil, wenn Sie dieselbe Impression/denselben Klick erneut auslösen. | ## Fehlerbehebung (Spezifisch für Shoppable Banner) | Symptom | Lösung | | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Erforderliche Produkt-Ereignisse kommen nicht an | Bestätigen Sie, dass das Banner Banner X mit Begleitprodukten in der Werbemittel-Phase verknüpft ist und dass `productImpression` und `productClick` auslösen mit `productCode`/`catalogId`. | | Impressionen werden bei jedem Scrollen/erneuten Rendern ausgelöst | Lösen Sie eine `productImpression` pro Produkt pro Sichtbarkeitsereignis aus; Entprellung anwenden. | | Registerkarte "Produkte" zeigt falsche oder fehlende Produkte an | Wahrscheinlich eine `productCode`/`catalogId` Abweichung vom Katalog – gleicht die von Ihnen gesendeten IDs mit dem Katalog-Feed ab. | | Warenkorb-Einheiten sehen falsch aus | Sie senden Deltas – senden Sie die absolute aktuelle `units`. | Für die allgemeine Endpunkt-Fehlerbehebung siehe den [Technische Referenz für das Reporting von Anzeigeninteraktions-Ereignissen](https://help.citrusad.com/retail-media-interface/integration/de/data-api/api-overview/ad-interaction-events-reporting) Abschnitt zur Fehlerbehebung. --- # 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/de/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.