> 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/it/data-api/api-overview/ad-interaction-events-reporting/integrate-banner-x-video-interaction-reporting.md).

# Integrare la segnalazione delle interazioni per Banner X Video

## Cosa abilita questo

I report sui video mostrano fino a che punto i clienti guardano un video — visualizzazione del materiale creativo, riproduzione, avanzamento per quartili e completamento — oltre alle azioni di controllo (salta, metti in pausa, disattiva audio). Funziona per Banner X materiale creativo video.

Banner X il video viene in genere riprodotto tramite un lettore VAST 4.0 anch'esso integrato, quindi il modo più rapido per abilitare questi report consiste nel lasciar inviare gli eventi al lettore al posto tuo: Epsilon restituisce un tag VAST nel campo `adm` della risposta dell'annuncio e tu inserisci un blocco `<TrackingEvents>` che punta ciascun traguardo di riproduzione all'endpoint delle interazioni. Questa guida mostra come creare tale blocco. Se il tuo lettore non può emettere il tracciamento VAST (o il video non viene erogato tramite VAST), usa invece [fallback manuale del beacon](#alternative--fire-beacons-from-player-callbacks) invece.

Questa guida copre solo le tipologie di interazione video e come collegarle tramite VAST. Per l'endpoint, l'autenticazione, i campi principali, i meccanismi di beacon, la deduplicazione e il testing, consulta il [**Riferimento tecnico**](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference).

## Prerequisiti

| Prerequisito                                                                                                            | Perché è importante                                                                                                                                    |
| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Leggi [Riferimento tecnico](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) | Copre l'endpoint, l'autenticazione, i campi principali e le regole di deduplicazione utilizzate da tutti gli eventi video.                             |
| Gli annunci erogati restituiscono un `adId` (`citrusAdId`)                                                              | Garantisce che ogni interazione video possa essere attribuita all'annuncio erogato.                                                                    |
| Un lettore compatibile con VAST 4.0 che riproduce il tag `adm` e attiva `<TrackingEvents>`                              | Il lettore attiva i beacon inseriti sul reale avanzamento della riproduzione.                                                                          |
| Il lettore espande le macro VAST (ad es. `[TIMESTAMP]`, `[CACHEBUSTING]`)                                               | Consente al lettore di timbrare ciascun beacon al momento dell'invio invece di lasciarlo dedurre a te.                                                 |
| Leggi `UniversalAdId` `idValue` da ciascun `<Creative>`                                                                 | Questo è l'ID stabile per video che Epsilon utilizza come `videoId` per collegare l'intero funnel (un singolo annuncio può contenere più di un video). |
| ID di tracciamento coerente per sessione di annuncio                                                                    | Usa `sessionId`, `customerId`, or `dtmToken` in modo coerente cosicché i report possano unire gli eventi nell'arco della sessione.                     |

## Cosa Epsilon eroga oggi (e cosa aggiungi tu)

L'oggetto `adm` nella risposta Banner X è un tag VAST 4.0. Epsilon collega già il tracciamento di **impression** e **click** al suo interno (`<Impression>` e `<VideoClicks><ClickTracking>`). **Non** eroga il tracciamento di avanzamento e interazione: è proprio quello che vai a inserire tu.

L'endpoint delle interazioni accetta già tutti i tipi di video sottostanti. Colleghi i due aggiungendo un blocco `<TrackingEvents>` i cui URL sono beacon `GET /v1/events/ad/interaction` . Quando il lettore supera ciascun traguardo, attiva l'URL corrispondente. Lascia i nodi Epsilonerogati da `<Impression>` e `<ClickTracking>` esattamente come sono — stai solo **aggiungendo** `<TrackingEvents>`.

## Tipi di interazione per i report video

Invia i campi principali più `videoId` su ogni evento video. `iabConsentString` è il campo opzionale su tutti i tipi (codificato in formato URL). Attiva gli eventi del funnel in ordine man mano che il lettore raggiunge ciascun traguardo, riutilizzando gli stessi `adId`, `videoId`e ID di tracciamento per l'intera sessione di visualizzazione.

### Eventi del funnel

| `interactionType`    | Quando attivare                                                                                  | Scopo del report                                                                              |
| -------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `videoCreativeView`  | Primo fotogramma video riprodotto                                                                | Baseline delle impression video                                                               |
| `videoPlay`          | La riproduzione si avvia (inviata dall'utente o riproduzione automatica in base all'informativa) | Tasso di avvio del video                                                                      |
| `videoFirstQuartile` | 25% della durata guardata                                                                        | Q1 del funnel video                                                                           |
| `videoMidpoint`      | 50% guardato                                                                                     | Q2 del funnel video                                                                           |
| `videoThirdQuartile` | 75% guardato                                                                                     | Q3 del funnel video                                                                           |
| `videoComplete`      | 100% guardato                                                                                    | Tasso di completamento — efficacia del materiale creativo e giustificazione della spesa video |

### Eventi di controllo

| `interactionType` | Quando attivare                        | Scopo del report                                          |
| ----------------- | -------------------------------------- | --------------------------------------------------------- |
| `videoSkip`       | L'utente salta prima del completamento | Tasso di skip — drop-off / problemi di materiale creativo |
| `videoPause`      | L'utente mette in pausa                | Profondità di coinvolgimento / distrazione                |
| `videoResume`     | L'utente riprende dopo la pausa        | Nuovo coinvolgimento dopo la pausa                        |
| `videoMute`       | L'utente disattiva l'audio             | Preferenza di coinvolgimento audio                        |
| `videoUnmute`     | L'utente riattiva l'audio              | Interesse audio attivo                                    |

## Mappa gli eventi VAST a Epsilon tipi di interazione

I player VAST inviano `<Tracking event="…">` callback standard. Inserisci un `<Tracking>` nodo per riga qui sotto, puntando all'endpoint di interazione con il relativo `interactionType`.

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

Altri eventi VAST non menzionati sopra (ad es. `progress`, `fullscreen`, `exitFullscreen`, `rewind`, `close`) non fanno parte del Epsilon reporting video — non inserire beacon per essi.

## Costruisci l'URL di tracciamento

Ogni URL `<Tracking>` inserito è un singolo beacon `GET` codificato in URL. Popolalo al momento della build con i valori della risposta dell'annuncio e usa una macro VAST per il timestamp in modo che il player lo registri al momento dell'invio.

```
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` — leggi `citrusAdId` dal banner erogato.
* `videoId` — leggi `idValue` dal `<UniversalAdId>` del materiale creativo che stai collegando. Questo è per singolo materiale creativo: se un annuncio contiene più video, ciascuno `<Creative>` ottiene il proprio `<TrackingEvents>` blocco utilizzando il `idValue`di **quel** materiale creativo, in modo che il funnel si ricolleghi al video effettivamente guardato.
* `sessionId` — inserisci il tuo `sessionId` (or `customerId` / `dtmToken`) al momento della build; l'endpoint rifiuta gli eventi privi di tracking id.
* `timestamp` — usa il `[TIMESTAMP]` macro VAST in modo che il player sostituisca il tempo reale di attivazione ISO 8601. Se il tuo player non lo supporta, apponi il timestamp del beacon in un altro modo, ma non inserire un unico orario fisso per tutti gli eventi.
* Aggiungi `[CACHEBUSTING]` come parametro fittizio se il tuo player memorizza in cache URL identici.

## Inserisci `<TrackingEvents>` nel tag VAST erogato

Aggiungi un `<TrackingEvents>` blocco all'interno di ciascun `<Creative>`'s `<Linear>` elemento (dopo `<VideoClicks>`, corrispondente all'esempio VAST 4.0). Di seguito, i `<Impression>` e `<ClickTracking>` sono Epsilonerogati e lasciati inalterati; il evidenziato `<TrackingEvents>` blocco è ciò che aggiungi. Nota `videoId` riutilizza questo del materiale creativo `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" %}
**Più video in un unico annuncio** Ripeti il `<TrackingEvents>` blocco per ogni `<Creative>`, ciascuno utilizzando il proprio `UniversalAdId` `idValue` as `videoId`. **Non condividere mai un `idValue`** tra i materiali creativi — questo è ciò che consente a Epsilon di attribuire il funnel al video specifico erogato.\*\*
{% endhint %}

## Sequenza di riproduzione

Gli eventi del funnel seguono questo ordine durante una visualizzazione completa:

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

| Regola                      | Guida                                                                                                                                                                  |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tappe del funnel            | Devono essere collegate al reale progresso della riproduzione. I player VAST attivano i quartili sul progresso effettivo; non sintetizzarli durante la ricerca (seek). |
| Eventi di controllo         | `videoSkip`, `videoPause`, `videoResume`, `videoMute`, e `videoUnmute` possono attivarsi in qualsiasi momento durante la riproduzione.                                 |
| Attribuzione della sessione | Riutilizza lo stesso `adId`, `videoId` (`idValue`), e ID di tracciamento durante tutta la sessione in modo che il funnel sia collegato.                                |

## Alternativa — invia beacon dai callback del lettore

Se il tuo lettore non può emettere VAST `<TrackingEvents>`, o il video non viene erogato tramite VAST, invia gli stessi beacon direttamente dai callback del lettore. L'endpoint e i campi sono identici — stai solo costruendo l'URL nel codice invece che nel tag VAST.

### Passaggio 1 — Acquisisci il contesto

Leggi `adId` (`citrusAdId`) e del materiale creativo `UniversalAdId` `idValue` da usare come `videoId`. Riutilizza l'ID di tracciamento della sessione.

### Passaggio 2 — Invia le tappe del funnel dai callback del lettore

```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"));
```

### Passaggio 3 — Invia gli eventi di controllo quando si verificano

Collega salta/pausa/riprendi/disattiva audio/attiva audio e invia il tipo corrispondente. Elimina i rimbalzi delle attivazioni rapide.

## Esempi di richieste

Gli URL VAST iniettati e i beacon manuali portano allo stesso `GET` richiesta. Gli URL completi sottostanti sono mandati a capo per leggibilità — inviali come un'unica stringa di query codificata.

### Riproduzione video

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

### Tappa quartile

Stessa struttura per `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
```

### Evento di controllo

Stessa struttura per `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
```

## Esempio di configurazione ottimale

| Area                   | Risultato previsto                                                                                                                               |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Tracciamento iniettato | Ciascun `<Creative>` contiene un `<TrackingEvents>` blocco; ogni `<Tracking>` URL utilizza quello del materiale creativo `idValue` as `videoId`. |
| Eventi quartile        | I quartili arrivano in ordine, con esattamente un `videoComplete` per una visualizzazione completa.                                              |
| Eventi di controllo    | Gli eventi non si duplicano oltre le regole di deduplicazione.                                                                                   |
| Nuove visualizzazioni  | Le nuove visualizzazioni nella stessa sessione riutilizzano `videoId` e rimangono attribuibili.                                                  |

## Risoluzione dei problemi (Specifiche del video)

| Problema                                                                         | Causa probabile                                                                       | Azione                                                                                                                     |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Non arriva alcun evento di avanzamento, solo impression/clic                     | `<TrackingEvents>` non iniettato, o aggiunto all'esterno `<Linear>`.                  | Aggiungi il blocco all'interno di ciascun `<Creative>`'s `<Linear>` e conferma che il lettore lo analizzi.                 |
| Tutti gli eventi condividono un unico timestamp                                  | `[TIMESTAMP]` macro non espansa dal lettore.                                          | Conferma il supporto per la macro, o apponi il timestamp per ogni invio; non inserire un unico orario fisso nel codice.    |
| Gli eventi arrivano ma non possono essere attribuiti a un video                  | `videoId` mancante o riutilizzato tra i materiali creativi.                           | Imposta `videoId` al proprio materiale creativo `UniversalAdId` `idValue`.                                                 |
| Gli eventi restituiscono HTTP 400                                                | URL non codificato, ID di tracciamento mancante o sconosciuto `interactionType`.      | Codifica in formato URL l'intero `<Tracking>` URL; includi `sessionId`/`customerId`/`dtmToken`; usa l'esatto tipo mappato. |
| Gli eventi compaiono ad intervalli fissi anziché corrispondere alla riproduzione | Beacon inviati su base temporizzata anziché sull'avanzamento reale.                   | Collega ciascun evento ai callback di avanzamento effettivi del lettore (VAST lo fa per te).                               |
| `videoComplete` invia più di una volta                                           | Il gestore di completamento si attiva anche in caso di ciclo continuo o riproduzione. | Elimina i rimbalzi e limita a un singolo completamento per riproduzione.                                                   |
| `videoComplete` si attiva al caricamento                                         | L'evento di completamento è legato al caricamento anziché al 100% della riproduzione. | Collega `videoComplete` alla reale fine della riproduzione.                                                                |

Per la risoluzione generale dei problemi con gli endpoint, consulta la [Riferimento tecnico](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) sezione di risoluzione dei problemi.

<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/it/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.