> 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-video-interaction-reporting.md).

# Intégrer le rapport d'interaction vidéo Banner X

## Ce que cela active

Les rapports vidéo montrent jusqu'où les acheteurs regardent — affichage de la création, lecture, progression par quartile et finalisation — ainsi que les actions de contrôle (ignorer, mettre en pause, couper le son). Cela fonctionne pour Banner X création vidéo.

Banner X la vidéo est généralement restituée via un lecteur VAST 4.0 que vous avez également intégré, donc le moyen le plus rapide d'activer ce rapport est de laisser le lecteur déclencher les événements pour vous : Epsilon renvoie une balise VAST dans le `adm` champ de la réponse publicitaire, et vous injectez un `<TrackingEvents>` bloc qui pointe chaque étape de lecture vers le point de terminaison d'interaction. Ce guide montre comment construire ce bloc. Si votre lecteur ne peut pas émettre de suivi VAST (ou si la vidéo n'est pas diffusée via VAST), utilisez le [fallback par balise manuelle](#alternative--fire-beacons-from-player-callbacks) à la place.

Ce guide couvre uniquement les types d'interaction vidéo et la manière de les lier via VAST. Pour le point de terminaison, l'authentification, les champs principaux, la mécanique des balises, la déduplication et les tests, consultez le [**Référence technique**](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference).

## Prérequis

| Prérequis                                                                                                                      | Pourquoi c'est important                                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Consultez le [Référence technique](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) | Couvre le point de terminaison, l'authentification, les champs principaux et les règles de déduplication utilisés par tous les événements vidéo.                           |
| Les publicités diffusées renvoient un réalisé `adId` (`citrusAdId`)                                                            | Garantit que chaque interaction vidéo peut être attribuée à la publicité diffusée.                                                                                         |
| Un lecteur compatible VAST 4.0 qui restitue la `adm` balise et déclenche `<TrackingEvents>`                                    | Le lecteur déclenche les balises injectées lors de la progression réelle de la lecture.                                                                                    |
| Le lecteur développe les macros VAST (par ex. `[TIMESTAMP]`, `[CACHEBUSTING]`)                                                 | Permet au lecteur de dater chaque balise au moment du déclenchement au lieu de la déduire vous-même.                                                                       |
| Vous lisez `UniversalAdId` `idValue` de chaque `<Creative>`                                                                    | Il s'agit de l'identifiant stable par vidéo que Epsilon utilise comme `videoId` pour lier le entonnoir de conversion (une seule publicité peut contenir plusieurs vidéos). |
| Identifiant de suivi cohérent par session publicitaire                                                                         | Utilisez `sessionId`, `customerId`, or `dtmToken` de manière cohérente afin que les rapports puissent associer les événements tout au long de la session.                  |

## Ce que Epsilon diffuse aujourd'hui (et ce que vous ajoutez)

L'objet `adm` dans la Banner X réponse est une balise VAST 4.0. Epsilon intègre déjà le suivi des **impressions** et des **clics** (`<Impression>` et `<VideoClicks><ClickTracking>`). Il ne **diffuse pas** le suivi de la progression et de l'interaction — c'est ce que vous injectez.

Le point de terminaison d'interaction accepte déjà tous les types de vidéo ci-dessous. Vous faites la liaison entre les deux en ajoutant un `<TrackingEvents>` bloc dont les URL sont des `GET /v1/events/ad/interaction` balises. Lorsque le lecteur franchit chaque étape, il déclenche l'URL correspondante. Laissez les nœuds Epsilondiffusés par `<Impression>` et `<ClickTracking>` exactement tels qu'ils sont — vous ne faites qu'**ajouter** des `<TrackingEvents>`.

## Types d'interaction pour les rapports vidéo

Envoyez les champs principaux plus `videoId` sur chaque événement vidéo. `iabConsentString` est le champ facultatif sur tous les types (encodé URL). Déclenchez les événements de l'entonnoir dans l'ordre à mesure que le lecteur atteint chaque étape, en réutilisant le même `adId`, `videoId`et l'identifiant de suivi pour toute la session de visionnage.

### Événements de l'entonnoir

| `interactionType`    | Quand déclencher                                                                          | Objectif du rapport                                                                  |
| -------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `videoCreativeView`  | Première image vidéo restituée                                                            | Ligne de base d'impression vidéo                                                     |
| `videoPlay`          | La lecture commence (initiée par l'utilisateur ou lecture automatique selon la politique) | Taux de démarrage vidéo                                                              |
| `videoFirstQuartile` | 25 % de la durée visionnée                                                                | Entonnoir vidéo Q1                                                                   |
| `videoMidpoint`      | 50 % visionnés                                                                            | Entonnoir vidéo Q2                                                                   |
| `videoThirdQuartile` | 75 % visionnés                                                                            | Entonnoir vidéo Q3                                                                   |
| `videoComplete`      | 100 % visionnés                                                                           | Taux de finalisation — efficacité de la création et justification des dépenses vidéo |

### Événements de contrôle

| `interactionType` | Quand déclencher                      | Objectif du rapport                               |
| ----------------- | ------------------------------------- | ------------------------------------------------- |
| `videoSkip`       | L'utilisateur passe avant la fin      | Taux d'abandon — problèmes de drop-off / création |
| `videoPause`      | L'utilisateur met en pause            | Profondeur d'engagement / distraction             |
| `videoResume`     | L'utilisateur reprend après une pause | Réengagement après une pause                      |
| `videoMute`       | L'utilisateur coupe le son            | Préférence d'engagement audio                     |
| `videoUnmute`     | L'utilisateur réactive le son         | Intérêt audio actif                               |

## Associer les événements VAST aux Epsilon types d'interaction

Les lecteurs VAST déclenchent des `<Tracking event="…">` rappels standard. Injectez un `<Tracking>` nœud par ligne ci-dessous, pointant vers le point de terminaison d'interaction avec le VAST `interactionType`.

| mappé `<Tracking event>` | Epsilon `interactionType` |
| ------------------------ | ------------------------- |
| `creativeView`           | `videoCreativeView`       |
| `start`                  | `videoPlay`               |
| `firstQuartile`          | `videoFirstQuartile`      |
| `midpoint`               | `videoMidpoint`           |
| `thirdQuartile`          | `videoThirdQuartile`      |
| `complete`               | `videoComplete`           |
| `skip`                   | `videoSkip`               |
| `pause`                  | `videoPause`              |
| `resume`                 | `videoResume`             |
| `mute`                   | `videoMute`               |
| `unmute`                 | `videoUnmute`             |

Les autres événements VAST non mentionnés ci-dessus (par ex. `progress`, `fullscreen`, `exitFullscreen`, `rewind`, `close`) ne font pas partie du Epsilon reporting vidéo — n'injectez pas de balises pour eux.

## Construire l'URL de suivi

Chaque URL `<Tracking>` injectée est une balise unique, encodée au format URL `GET` Alimentez-la au moment de la construction avec les valeurs de la réponse publicitaire, et utilisez une macro VAST pour l'horodatage afin que le lecteur le marque au moment du déclenchement.

```
https://integration.{url}.citrusad.com/v1/events/ad/interaction
  ?adId={citrusAdId}
  &interactionType={mapped type, e.g. videoFirstQuartile}
  &videoId={UniversalAdId idValue for this creative}
  &sessionId={your session tracking id}
  &timestamp=[TIMESTAMP]
```

* `adId` — lire `citrusAdId` à partir de la bannière diffusée.
* `videoId` — lire `idValue` à partir du `<UniversalAdId>` de la création que vous câblez. Cela s'applique par création : si une publicité contient plusieurs vidéos, chacune `<Creative>` obtient son propre `<TrackingEvents>` bloc en utilisant le `idValue`de **cette** création, afin que le entonnoir soit lié à la vidéo réellement regardée.
* `sessionId` — injectez votre `sessionId` (or `customerId` / `dtmToken`) au moment de la construction ; le point de terminaison rejette les événements sans identifiant de suivi.
* `timestamp` — utilisez la macro VAST `[TIMESTAMP]` afin que le lecteur la remplace par l'heure réelle de déclenchement au format ISO 8601. Si votre lecteur ne la prend pas en charge, marquez la balise d'une autre manière, mais ne coduz pas en dur une heure unique pour tous les événements.
* Ajouter `[CACHEBUSTING]` comme paramètre jetable si votre lecteur met en cache des URL identiques.

## Injecter `<TrackingEvents>` dans le tag VAST diffusé

Ajoutez un `<TrackingEvents>` bloc à l'intérieur de chaque `<Creative>`'s `<Linear>` élément (après `<VideoClicks>`conforme à l'échantillon VAST 4.0). Ci-dessous, les `<Impression>` et `<ClickTracking>` sont servis par Epsilonet laissés intacts ; le bloc `<TrackingEvents>` mis en surbrillance est ce que vous ajoutez. Notez que `videoId` réutilise le `idValue` (`…000003`).

```xml
<Creative>
  <UniversalAdId idRegistry="citrusad.com" idValue="00000000-0000-0000-0000-000000000003">
    00000000-0000-0000-0000-000000000003
  </UniversalAdId>
  <Linear>
    <Duration>00:00:15</Duration>
    <MediaFiles>
      <MediaFile delivery="progressive" type="video/mp4" width="1920" height="1080">
        <![CDATA[https://example.com/media/example-video-2.mp4]]>
      </MediaFile>
    </MediaFiles>
    <VideoClicks>
      <ClickTracking>
        <![CDATA[https://integration.{retailer}.citrusad.com/v1/resource/second-c/example_ad_id]]>
      </ClickTracking>
      <ClickThrough></ClickThrough>
    </VideoClicks>

    <!-- Injected by the retailer: maps VAST playback events to the Epsilon interaction endpoint -->
    <TrackingEvents>
      <Tracking event="creativeView"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoCreativeView&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="start"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoPlay&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="firstQuartile"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoFirstQuartile&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="midpoint"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoMidpoint&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="thirdQuartile"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoThirdQuartile&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="complete"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoComplete&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="skip"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoSkip&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="pause"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoPause&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="resume"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoResume&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="mute"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoMute&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="unmute"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoUnmute&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
    </TrackingEvents>
  </Linear>
</Creative>
```

{% hint style="info" %}
de cette création **Plusieurs vidéos dans une seule publicité** Répétez le `<TrackingEvents>` bloc pour chaque `<Creative>`, chacun utilisant son propre `UniversalAdId` `idValue` as `videoId`. **Ne partagez jamais un `idValue`** entre plusieurs créations — c'est ce qui permet à\*\* Epsilon **d'attribuer l'entonnoir à la vidéo spécifique diffusée.**
{% endhint %}

## Séquence de lecture

Les événements de l'entonnoir suivent cet ordre sur une vue complète :

`videoCreativeView` → `videoPlay` → `videoFirstQuartile` → `videoMidpoint` → `videoThirdQuartile` → `videoComplete`

| Règle                    | Conseils                                                                                                                                                                   |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Étape clé de l'entonnoir | Doit être lié à la progression réelle de la lecture. Les lecteurs VAST déclenchent des quartiles sur une progression réelle ; ne les synthétisez pas lors d'une recherche. |
| Événements de contrôle   | `videoSkip`, `videoPause`, `videoResume`, `videoMute`, et `videoUnmute` peuvent se déclencher à tout moment pendant la lecture.                                            |
| Attribution de session   | Réutilisez le même `adId`, `videoId` (`idValue`), et l'identifiant de suivi tout au long de la session afin que l'entonnoir se lie.                                        |

## Alternative — déclenchez des balises depuis les rappels du lecteur

Si votre lecteur ne peut pas émettre de VAST `<TrackingEvents>`, ou si la vidéo n'est pas servie via VAST, déclenchez les mêmes balises directement depuis les rappels du lecteur. Le point d'accès et les champs sont identiques — vous construisez simplement l'URL dans le code au lieu de le faire dans la balise VAST.

### Étape 1 — Capturer le contexte

Lisez `adId` (`citrusAdId`) et la création `UniversalAdId` `idValue` à utiliser comme `videoId`. Réutilisez l'ID de suivi de session.

### Étape 2 — Déclencher les étapes du entonnoir depuis les rappels du lecteur

```javascript
function fireVideo(interactionType) {
  navigator.sendBeacon(
    "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" +
    new URLSearchParams({
      adId, interactionType, videoId, sessionId,
      timestamp: new Date().toISOString()
    })
  );
}
// e.g. player.on("firstquartile", () => fireVideo("videoFirstQuartile"));
```

### Étape 3 — Déclencher les événements de contrôle au fur et à mesure qu'ils se produisent

Associez passer/pause/reprendre/sourdine/réactiver le son et déclenchez le type correspondant. Anti-rebondissez les bascules rapides.

## Exemples de requêtes

Les URL VAST injectées et les balises manuelles aboutissent à la même `GET` requête. Les URL complètes ci-dessous sont retournées à la ligne pour plus de lisibilité — envoyez-les sous forme de chaîne de requête encodée unique.

### Lecture vidéo

```http
GET https://integration.retailer.citrusad.com/v1/events/ad/interaction
  ?adId=banner_vid001
  &timestamp=2026-05-20T10:20:00Z
  &sessionId=sess_001
  &interactionType=videoPlay
  &videoId=00000000-0000-0000-0000-000000000003
```

### Étape de quartile

Même structure pour `videoFirstQuartile` / `videoMidpoint` / `videoThirdQuartile` / `videoComplete`.

```http
GET https://integration.retailer.citrusad.com/v1/events/ad/interaction
  ?adId=banner_vid001
  &timestamp=2026-05-20T10:20:15Z
  &sessionId=sess_001
  &interactionType=videoFirstQuartile
  &videoId=00000000-0000-0000-0000-000000000003
```

### Événement de contrôle

Même structure pour `videoSkip` / `videoPause` / `videoResume` / `videoMute` / `videoUnmute`.

```http
GET https://integration.retailer.citrusad.com/v1/events/ad/interaction
  ?adId=banner_vid001
  &timestamp=2026-05-20T10:20:40Z
  &sessionId=sess_001
  &interactionType=videoSkip
  &videoId=00000000-0000-0000-0000-000000000003
```

## À quoi ressemble un résultat correct

| Zone                   | Résultat attendu                                                                                                                   |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Suivi injecté          | Chaque `<Creative>` transporte un `<TrackingEvents>` bloc ; chaque `<Tracking>` URL utilise cette Création `idValue` as `videoId`. |
| Événements de quartile | Les quartiles arrivent dans l'ordre, avec exactement un `videoComplete` pour un visionnage complet.                                |
| Événements de contrôle | Les événements ne se dupliquent pas au-delà des règles de déduplication.                                                           |
| Nouveaux visionnages   | Les nouveaux visionnages au cours de la même session réutilisent `videoId` et restent attribuables.                                |

## Dépannage (spécificités vidéo)

| Problème                                                                                | Cause probable                                                                      | Action                                                                                                              |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Aucun événement de progression n'arrive, seulement impression/clic                      | `<TrackingEvents>` non injecté, ou ajouté en dehors de `<Linear>`.                  | Ajoutez le bloc à l'intérieur de chaque `<Creative>`'s `<Linear>` et confirmez que le lecteur le sépare.            |
| Tous les événements partagent un seul horodatage                                        | `[TIMESTAMP]` macro non développée par le lecteur.                                  | Confirmez le support des macros, ou horodatez à chaque déclenchement ; ne codiz pas en dur une seule heure.         |
| Les événements arrivent mais ne peuvent pas être attribués à une vidéo                  | `videoId` manquant ou réutilisé entre les créations.                                | Définissez `videoId` pour chaque Création `UniversalAdId` `idValue`.                                                |
| Les événements renvoient HTTP 400                                                       | URL non encodée, ID de suivi manquant ou inconnu `interactionType`.                 | Encodez l'URL entière `<Tracking>` URL ; incluez `sessionId`/`customerId`/`dtmToken`; utilisez le type mappé exact. |
| Les événements apparaissent à des intervalles fixes plutôt qu'en fonction de la lecture | Balises déclenchées sur un minuteur plutôt que sur la progression réelle.           | Liez chaque événement aux rappels de progression réels du lecteur (VAST le fait pour vous).                         |
| `videoComplete` se déclenche plus d'une fois                                            | Le gestionnaire de fin se déclenche également lors d'une boucle ou d'une relecture. | Anti-rebondissez et limitez à une seule fin par lecture.                                                            |
| `videoComplete` se déclenche au chargement                                              | L'événement de fin est lié au chargement plutôt qu'à la lecture à 100 %.            | Liez `videoComplete` à la vraie fin de lecture.                                                                     |

Pour le dépannage général des points d'accès, consultez la [Référence technique](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) section de dépannage.

<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/integrate-banner-x-video-interaction-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.