> 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.md).

# Rapports sur les événements d'interaction avec l'annonce

Les rapports sur les événements d'interaction avec les annonces offrent un niveau de rapport supplémentaire aux campagnes, permettant à vous et à vos marques de comprendre comment les clients interagissent avec vos annonces.

Achetable Banner X et Vidéo Banner X les intégrations envoient des événements au même point de terminaison avec le même transport, la même authentification et les mêmes champs principaux. Lisez ceci une fois, puis suivez le guide pour le rapport que vous souhaitez activer.

## Comment les intégrations s'articulent

Le point de terminaison des interactions alimente trois résultats de rapport. Cette page est la référence partagée ; chaque résultat a son propre guide de tâches qui renvoie ici pour la configuration technique.

```
Ad serving (returns a realised adId)
        │
        ▼
GET /v1/events/ad/interaction   ← this reference: transport, auth, core fields, dedup, errors
        │
        ├─ adInteraction .......... Shoppable Banner reporting
        └─ adInteraction .......... Video reporting
```

| Résultat           | Point de terminaison | Types d'interaction (résumé)                                     |
| ------------------ | -------------------- | ---------------------------------------------------------------- |
| Bannière achetable | ad/interaction       | productImpression, productClick, creativeClick, cart             |
| Vidéo              | ad/interaction       | videoCréationView, videoPlay, quartiles, videoComplete, controls |

## Avant de commencer (prérequis partagés)

| Prérequis                                                                                                  | Objectif                                                                                       |
| ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Espace de noms du distributeur / catalogue configuré et URL de base d'intégration émise                    | Confirme que l'environnement du distributeur est prêt à recevoir des événements d'interaction. |
| Les annonces diffusées renvoient un adId                                                                   | Permet d'associer chaque événement à l'annonce diffusée.                                       |
| ID de catalogue (productCode, catalogId) disponibles dans le contexte de l'annonce ; videoId pour la vidéo | Fournit le contexte de produit ou de vidéo nécessaire pour le guide de rapport correspondant.  |
| ID de suivi cohérents (sessionId, customerId, ou dtmToken) par session publicitaire                        | Permet l'attribution et la déduplication entre les événements d'une même session.              |
| Activation des rapports confirmée pour le compte                                                           | Garantit que les événements acceptés peuvent alimenter les sorties de rapport.                 |

### Point de terminaison et transport

* Méthode :\*\* HTTPS `GET` avec paramètres de requête ; pas de corps de requête.
* Point de terminaison : `GET https://integration.{retailer}.citrusad.com/v1/events/ad/interaction`
* Réponse : `HTTP 200` en cas d'acceptation, `HTTP 400` en cas d'échec de validation, `5xx` en cas d'erreur de plateforme.

### Authentification et sécurité

* Sans confirmation (Fire-and-forget) :\*\* utilisez `navigator.sendBeacon`, une image 1×1, ou `fetch(…, { keepalive: true })` pour que les événements survivent au déchargement de la page.
* **Ne réessayez pas un HTTP 400** — il est mal formé et échouera à nouveau. Corrigez plutôt la requête.
* **Encodez toutes les valeurs dans l'URL**, en particulier la chaîne de consentement et tous les champs d'URL.

### Champs principaux (chaque événement)

| Champ                                   | Type   | Requis            | Description                                                                                                    | Valeurs acceptées                 |
| --------------------------------------- | ------ | ----------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `adId`                                  | string | Oui               | ID d'annonce réalisée à partir de l'annonce diffusée                                                           | —                                 |
| `interactionType`                       | string | Oui               | Type d'événement (camelCase sensible à la casse)                                                               | Consultez les guides par résultat |
| `timestamp`                             | string | Oui               | Heure de l'événement (ISO 8601 ; utilisez UTC ou l'heure locale du distributeur de manière cohérente)          | ISO 8601                          |
| `sessionId` / `customerId` / `dtmToken` | string | Oui (au moins un) | ID de suivi — au moins un requis ; si tous sont manquants, l'événement ne peut pas être attribué et est rejeté | —                                 |

Réutilisez un ID de suivi pour toute la session publicitaire et réutilisez le même `adId` pour chaque événement de cette annonce diffusée. Chaque `interactionType` associe à une métrique de rapport spécifique — consultez le guide par résultat pour la « finalité du rapport » de chaque type.

### Identifiants

Les ID qui lient les événements aux annonces, aux produits et aux sessions. Les exigences de champs par événement se trouvent dans chaque guide ; ceci est la définition partagée de l'origine de chaque ID.

| Identifiant                             | Ce que c'est                         | D'où cela provient                                | Utilisé par                        |
| --------------------------------------- | ------------------------------------ | ------------------------------------------------- | ---------------------------------- |
| `adId`                                  | ID de la publicité réalisée          | La réponse publicitaire servie                    | Chaque événement                   |
| `productCode` / `catalogId`             | SKU + son périmètre de catalogue     | Catalogue du distributeur / contexte publicitaire | Événements de produit et de panier |
| `videoId`                               | ID d'élément vidéo stable            | La création vidéo                                 | Événements vidéo                   |
| `creativeId`                            | ID d'élément de création non-produit | La création                                       | `creativeClick`                    |
| `sessionId` / `customerId` / `dtmToken` | ID de suivi (n'importe lequel)       | Session du distributeur / connexion / DTM         | Chaque événement                   |

### Modèle d'implémentation (Balise)

Utilisez une image 1×1, `fetch` avec `keepalive`, or `navigator.sendBeacon` pointant vers l'URL GET complète. Ne vous fiez pas à l'analyse du corps de la réponse pour l'expérience utilisateur. Le même assistant sert les trois intégrations — les guides par résultat diffèrent uniquement par les `interactionType` et les champs que vous transmettez.

```javascript
function fireAdInteraction(params) {
  const qs = new URLSearchParams(params);
  const url = `https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?${qs}`;
  if (navigator.sendBeacon) {
    navigator.sendBeacon(url);
  } else {
    new Image().src = url; // fallback
  }
}

// Example: product click (see the Shoppable Banner guide for the full set)
fireAdInteraction({
  adId: "shotgun_0001",
  timestamp: new Date().toISOString(),
  sessionId: getSessionId(),
  productCode: "prod-00001-01",
  catalogId: "catlg-custom-DAA001",
  interactionType: "productClick",
});
```

<br>


---

# 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.md?ask=<question>&goal=<endgoal>
```

`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.