> 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/fr/data-api/api-overview/ad-interaction-events-reporting/integrate-banner-x-shoppable-banner-interaction-reporting.md). # Intégrer le rapport d'interaction Banner X Shoppable Banner Une bannière Shoppable est une Banner X publicité comportant plusieurs zones d'interaction de produits associés dans un seul emplacement. Une fois ces événements transmis, le rapport de campagne détaille les performances de la bannière pour chaque produit associé (impressions, clics et CTR, ainsi que les actions d'ajout au panier si intégrées), au lieu d'afficher un total unique au niveau de la bannière. Ce guide couvre uniquement les types d'interaction de la bannière Shoppable. Pour ce qui concerne le point de terminaison, l'authentification, les champs principaux (`adId`, `timestamp`, ID de suivi), le fonctionnement des balises, la déduplication et les tests, consultez le [Référence technique du rapport sur les événements d'interaction publicitaire](https://help.citrusad.com/retail-media-interface/integration/fr/data-api/api-overview/ad-interaction-events-reporting). ## Conditions préalables | Condition préalable | Objectif | | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Lisez le [Référence technique](https://help.citrusad.com/retail-media-interface/integration/fr/data-api/api-overview/ad-interaction-events-reporting) | Confirme le point de terminaison, l'authentification, les champs principaux et les exigences de déduplication. | | Produits associés configurés sur la Banner X Création | S'assure que les interactions au niveau du produit peuvent être attribuées à la création. | | Les publicités diffusées renvoient un `adId` | Associe chaque événement à l'instance de publicité diffusée. | | `productCode` et `catalogId` disponible par produit associé | Identifie le produit et le catalogue utilisés dans les rapports. | | Règle de visibilité convenue pour les fiches produits | Définit le moment où une fiche produit est considérée comme vue pour `productImpression`. | | ID de suivi cohérent par session publicitaire | Prend en charge l'attribution et la déduplication à l'aide de `sessionId`, `customerId`, or `dtmToken`. | ## Types d'interaction pour le rapport de bannière Shoppable Il s'agit de `adInteraction` événements (pas de `moduleId`). Envoyez les champs principaux ainsi que les champs clés ci-dessous. `productImpression` et `productClick` sont les deux événements qui débloquent l'onglet Produits — déclenchez les deux. | `interactionType` | Champs clés | Quand déclencher | Objectif du rapport | | ------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `productImpression` | `productCode`, `catalogId` | Une fiche produit/un SKU devient visible selon vos règles de visibilité | Impressions par produit — remplit la colonne des impressions (et les lignes à zéro clic) | | `productClick` | `productCode`, `catalogId` | L'acheteur clique sur une fiche produit/un SKU | Clics par produit — génère les clics et le CTR | | `creativeClick` | `creativeId` | Clic sur un élément de création qui n'est pas un produit | Engagement avec une création qui n'est pas un produit | | `cart` | `productCode`, `catalogId`, `units`, facultatif `conversionValue` | Modification du panier depuis le contexte publicitaire | Intention d'ajout au panier / valeur du produit | ## Règles de visibilité pour `productImpression` | Règle | Conseils | | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Définir le moment où une fiche est considérée comme vue | Convenez d'une règle de visibilité, telle que le pourcentage visible plus le temps à l'écran, et appliquez-la de manière cohérente sur le Web et l'application. | | Déclencher les impressions une fois par occurrence de visibilité | Éliminez les rebonds dus au défilement et aux retracés afin qu'un affichage unique ne soit pas compté plusieurs fois. | ## Panier : Envoyer les unités actuelles absolues Déclenchez `cart` à chaque interaction avec le panier — ajout initial, chaque `+`, chaque `−`, et retrait (retour à `0`) — avec `units` défini sur le nombre absolu d'unités actuelles, et non une variation. Le renvoi du total actuel permet de conserver des décomptes exacts après déduplication. Ajoutez `conversionValue` lorsque vous l'avez. {% hint style="info" %} **Exemple** — un acheteur ajoute un produit, l'incrémente deux fois, puis le retire :\*\* `cart {units: 1}` → `cart {units: 2}` → `cart {units: 3}` → `cart {units: 0}` {% endhint %} ## Mise en œuvre étape par étape ### Étape 1 — Capturer le contexte publicitaire Lisez le `adId` réalisé à partir de la publicité diffusée, et `productCode`/`catalogId` pour chaque fiche associée. Établissez un ID de suivi pour la session et réutilisez-le sur les impressions et les clics. ### Étape 2 — Déclencher les impressions de produits Lorsqu'une fiche répond à votre règle de visibilité, déclenchez `productImpression` une fois pour ce produit. ```javascript navigator.sendBeacon( "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" + new URLSearchParams({ adId, interactionType: "productImpression", sessionId, timestamp: new Date().toISOString(), productCode, catalogId }) ); ``` ### Étape 3 — Déclencher un clic sur un produit ```javascript navigator.sendBeacon( "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" + new URLSearchParams({ adId, interactionType: "productClick", sessionId, timestamp: new Date().toISOString(), productCode, catalogId }) ); ``` ### Étape 4 — Déclencher les modifications du panier Lors d'un ajout/d'une mise à jour, déclenchez `cart` avec l'élément absolument actuel `units` pour ce produit (et `conversionValue` si vous l'avez) — voir la règle de panier ci-dessus. ## Exemples de requêtes URL GET complètes (renvoyées à la ligne pour une meilleure lisibilité — à envoyer sous forme d'une seule chaîne de requête encodée). ### Impression de produit ```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 ``` ### Clic sur le produit ```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 ``` ### Ajout au panier depuis une annonce ```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 ``` ## À quoi ressemble un résultat correct | Vérification | Détail | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Les événements renvoient le code HTTP 200 | `productImpression` et `productClick` renvoient le code HTTP 200 en PRE/QA. | | L'onglet Produits est entièrement renseigné | Chaque produit complémentaire configuré apparaît, y compris les lignes sans engagement (les impressions remplissent les lignes sans clic). | | La dédoublonnage fonctionne | Les décomptes restent stables lorsque vous déclenchez à nouveau la même impression/le même clic. | ## Dépannage (Spécificités des bannières achetables) | Symptôme | Correctif | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Les événements de produit requis n'arrivent pas | Confirmez que la bannière est Banner X avec des produits complémentaires au niveau de la création, et que `productImpression` et `productClick` déclencher avec `productCode`/`catalogId`. | | Impressions déclenchées à chaque défilement/nouvel affichage | Déclencher un `productImpression` par produit et par occurrence de visibilité ; anti-rebond. | | L'onglet Produits affiche des produits erronés ou manquants | Probablement une `productCode`/`catalogId` incohérence avec le catalogue — réconciliez les ID que vous envoyez avec le flux du catalogue. | | Les unités du panier semblent erronées | Vous envoyez des deltas — envoyez l'élément absolument actuel `units`. | Pour le dépannage général des points de terminaison, consultez la [Référence technique du rapport sur les événements d'interaction publicitaire](https://help.citrusad.com/retail-media-interface/integration/fr/data-api/api-overview/ad-interaction-events-reporting) section de dépannage. --- # 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/fr/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.