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

# Integrar la notificación de interacción de vídeo de Banner X

## Lo que esto activa

Los informes de vídeo muestran qué parte del vídeo ven los compradores (vista de la creatividad, reproducción, progreso por cuartiles y finalización), además de las acciones de control (omitir, pausar, silenciar). Funciona para Banner X creatividad de vídeo.

Banner X el vídeo se suele reproducir a través de un reproductor VAST 4.0 que también tienes integrado, por lo que la forma más rápida de habilitar estos informes es dejar que el reproductor active los eventos por ti: Epsilon devuelve una etiqueta VAST en el campo `adm` de la respuesta del anuncio, e inyectas un bloque `<TrackingEvents>` que apunta cada hito de reproducción al punto de conexión de interacción. Esta guía muestra cómo construir ese bloque. Si tu reproductor no puede emitir el seguimiento VAST (o el vídeo no se sirve a través de VAST), utiliza el [alternativa manual de beacon](#alternative--fire-beacons-from-player-callbacks) en su lugar.

Esta guía solo cubre los tipos de interacción de vídeo y cómo vincularlos a través de VAST. Para obtener información sobre el punto de conexión, la autenticación, los campos principales, la mecánica de balizas, la deduplicación y las pruebas, consulta el [**Referencia técnica**](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference).

## Requisitos previos

| Requisito previo                                                                                                        | Por qué es importante                                                                                                                         |
| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Lee el [Referencia técnica](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) | Cubre el punto de conexión, la autenticación, los campos principales y las reglas de deduplicación utilizadas por todos los eventos de vídeo. |
| Los anuncios servidos devuelven un `adId` (`citrusAdId`)                                                                | Garantiza que cada interacción de vídeo se pueda atribuir al anuncio entregado.                                                               |
| Un reproductor compatible con VAST 4.0 que procesa la etiqueta `adm` y activa `<TrackingEvents>`                        | El reproductor activa las balizas inyectadas en función del progreso real de la reproducción.                                                 |
| El reproductor expande las macros VAST (p. ej., `[TIMESTAMP]`, `[CACHEBUSTING]`)                                        | Permite que el reproductor selle cada baliza en el momento de la activación en lugar de que lo deduzcas tú.                                   |
| Lees `UniversalAdId` `idValue` de cada `<Creative>`                                                                     | Este es el ID estable por vídeo que Epsilon utiliza como `videoId` para vincular el embudo (un solo anuncio puede contener más de un vídeo).  |
| ID de seguimiento coherente por sesión de anuncio                                                                       | Utiliza `sessionId`, `customerId`, or `dtmToken` de forma coherente para que los informes puedan combinar eventos a lo largo de la sesión.    |

## Lo que Epsilon sirve hoy (y lo que añades)

El objeto `adm` en la respuesta Banner X es una etiqueta VAST 4.0. Epsilon ya vincula el seguimiento de **impresiones** y **clics** en ella (`<Impression>` y `<VideoClicks><ClickTracking>`). **No** sirve el seguimiento de progreso e interacción; eso es lo que inyectas tú.

El punto de conexión de interacción ya acepta todos los tipos de vídeo que se indican a continuación. Puedes vincular ambos añadiendo un bloque `<TrackingEvents>` cuyas URL sean balizas de `GET /v1/events/ad/interaction` . Cuando el reproductor supera cada hito, activa la URL correspondiente. Deja los nodos Epsilonservidos por `<Impression>` y `<ClickTracking>` exactamente como están; solo estás **añadiendo** `<TrackingEvents>`.

## Tipos de interacción para informes de vídeo

Envía los campos principales más `videoId` en cada evento de vídeo. `iabConsentString` es el campo opcional en todos los tipos (con codificación URL). Activa los eventos del embudo en orden a medida que el reproductor alcance cada hito, reutilizando el mismo `adId`, `videoId`e ID de seguimiento para toda la sesión de visualización.

### Eventos del embudo

| `interactionType`    | Cuándo activar                                                                                  | Propósito del informe                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `videoCreativeView`  | Primer fotograma de vídeo procesado                                                             | Línea base de impresiones de vídeo                                                  |
| `videoPlay`          | La reproducción se inicia (iniciada por el usuario o reproducción automática según la política) | Tasa de inicio de vídeo                                                             |
| `videoFirstQuartile` | 25 % de la duración vista                                                                       | Q1 del embudo de vídeo                                                              |
| `videoMidpoint`      | 50 % visto                                                                                      | Q2 del embudo de vídeo                                                              |
| `videoThirdQuartile` | 75 % visto                                                                                      | Q3 del embudo de vídeo                                                              |
| `videoComplete`      | 100 % visto                                                                                     | Tasa de finalización: eficacia de la creatividad y justificación del gasto en vídeo |

### Eventos de control

| `interactionType` | Cuándo activar                         | Propósito del informe                                    |
| ----------------- | -------------------------------------- | -------------------------------------------------------- |
| `videoSkip`       | El usuario omite antes de completar    | Tasa de omisión — abandono / problemas de la creatividad |
| `videoPause`      | El usuario hace una pausa              | Profundidad de interacción / distracción                 |
| `videoResume`     | El usuario reanuda después de la pausa | Reinteracción después de la pausa                        |
| `videoMute`       | El usuario silencia el audio           | Preferencia de interacción con el audio                  |
| `videoUnmute`     | El usuario desactiva el silencio       | Interés activo en el audio                               |

## Mapee los eventos VAST a Epsilon tipos de interacción

Los reproductores VAST activan estándar `<Tracking event="…">` callbacks. Inyecte un `<Tracking>` nodo por fila a continuación, apuntando al endpoint de interacción con el mapeado `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`             |

Otros eventos VAST sin mención anterior (por ejemplo, `progress`, `fullscreen`, `exitFullscreen`, `rewind`, `close`) no forman parte del Epsilon informe de vídeo — no inyecte beacons para ellos.

## Construya la URL de seguimiento

Cada inyectada `<Tracking>` URL es un único, codificado en URL `GET` beacon. Rellénelo en el momento de la creación con los valores de la respuesta del anuncio y utilice una macro VAST para la marca de tiempo para que el reproductor la selle en el momento del disparo.

```
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` — leer `citrusAdId` del banner servido.
* `videoId` — leer `idValue` de la `<UniversalAdId>` de la creatividad que está vinculando. Esto es por creatividad: si un anuncio contiene varios vídeos, cada uno `<Creative>` obtiene su propio `<TrackingEvents>` bloque usando la `idValue`de **esa** creatividad, para que el embudo se vincule de nuevo al vídeo que realmente se vio.
* `sessionId` — inyecte su `sessionId` (or `customerId` / `dtmToken`) en el momento de la creación; el endpoint rechaza eventos sin ID de seguimiento.
* `timestamp` — use la `[TIMESTAMP]` macro VAST para que el reproductor sustituya el tiempo de disparo real ISO 8601. Si su reproductor no lo admite, selle el beacon de otra manera, pero no deje fija una sola hora para todos los eventos.
* Añada `[CACHEBUSTING]` como un parámetro desechable si su reproductor almacena en caché URL idénticas.

## Inyecte `<TrackingEvents>` en la etiqueta VAST servida

Añada un `<TrackingEvents>` bloque dentro de cada `<Creative>`'s `<Linear>` elemento (después de `<VideoClicks>` coincidiendo con la muestra VAST 4.0). A continuación, los `<Impression>` y `<ClickTracking>` son Epsilonservidos y se dejan intactos; el destacado `<TrackingEvents>` bloque es lo que añade. Tenga en cuenta `videoId` reutiliza esta creatividad `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" %}
**Varios vídeos en un solo anuncio** Repita el `<TrackingEvents>` bloque para cada `<Creative>`, cada uno usando el suyo propio `UniversalAdId` `idValue` as `videoId`. **Nunca comparta uno `idValue`** entre creatividades — eso es lo que permite a Epsilon atribuir el embudo al vídeo específico servido.\*\*
{% endhint %}

## Secuencia de reproducción

Los eventos del embudo siguen este orden a lo largo de una visualización completa:

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

| Regla                | Guía                                                                                                                                                            |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hitos del embudo     | Deben estar vinculados al progreso real de la reproducción. Los reproductores VAST activan los cuartiles con el progreso real; no los sintetice en la búsqueda. |
| Eventos de control   | `videoSkip`, `videoPause`, `videoResume`, `videoMute`, y `videoUnmute` pueden activarse en cualquier momento durante la reproducción.                           |
| Atribución de sesión | Reutilice el mismo `adId`, `videoId` (`idValue`), e ID de seguimiento a lo largo de la sesión para que el embudo se vincule.                                    |

## Alternativa: activar balizas desde las llamadas de retorno del reproductor

Si su reproductor no puede emitir VAST `<TrackingEvents>`, o el vídeo no se sirve a través de VAST, active las mismas balizas directamente desde las llamadas de retorno del reproductor. El punto de enlace y los campos son idénticos; solo está construyendo la URL en el código en lugar de en la etiqueta VAST.

### Paso 1: Capturar el contexto

Leer `adId` (`citrusAdId`) y el de la creatividad `UniversalAdId` `idValue` para usar como `videoId`Reutilice el ID de seguimiento de la sesión.

### Paso 2: Activar los hitos del embudo desde las llamadas de retorno del reproductor

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

### Paso 3: Activar los eventos de control a medida que ocurren

Enganche omitir/pausar/reanudar/silenciar/desactivar silencio y active el tipo coincidente. Depure las alternancias rápidas.

## Muestra de solicitudes

Las URL VAST inyectadas y las balizas manuales se resuelven en la misma `GET` solicitud. Las URL completas a continuación se envuelven en líneas para mayor legibilidad; envíelas como una sola cadena de consulta codificada.

### Reproducción de 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
```

### Hito de cuartil

Misma forma para `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 de control

Misma forma para `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
```

## Cómo se ve un buen resultado

| Área                  | Resultado esperado                                                                                                            |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Seguimiento inyectado | Cada `<Creative>` lleva un `<TrackingEvents>` bloque; cada `<Tracking>` URL usa el de esa Creatividad `idValue` as `videoId`. |
| Eventos de cuartil    | Los cuartiles llegan en orden, con exactamente uno `videoComplete` para una visualización completa.                           |
| Eventos de control    | Los eventos no se duplican más allá de las reglas de deduplicación.                                                           |
| Volver a ver          | Las nuevas visualizaciones en la misma sesión reutilizan `videoId` y siguen siendo atribuibles.                               |

## Solución de problemas (específicos de video)

| Problema                                                                           | Causa probable                                                                              | Acción                                                                                                              |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| No llegan eventos de progreso, solo impresión/clic                                 | `<TrackingEvents>` no inyectado, o añadido fuera de `<Linear>`.                             | Añada el bloque dentro de cada `<Creative>`'s `<Linear>` y confirme que el reproductor lo analice.                  |
| Todos los eventos comparten una marca de tiempo                                    | `[TIMESTAMP]` macro no expandida por el reproductor.                                        | Confirme el soporte de macros o selle por disparo; no ponga una hora fija en el código.                             |
| Los eventos llegan pero no se pueden atribuir a un video                           | `videoId` faltante o reutilizado entre Creatividades.                                       | Establezca `videoId` para la propia Creatividad `UniversalAdId` `idValue`.                                          |
| Los eventos devuelven HTTP 400                                                     | URL no codificada, falta ID de seguimiento o desconocido `interactionType`.                 | Codifique en URL todo el `<Tracking>` URL; incluya `sessionId`/`customerId`/`dtmToken`; use el tipo mapeado exacto. |
| Los eventos aparecen en intervalos fijos en lugar de coincidir con la reproducción | Balizas activadas con un temporizador en lugar de un progreso real.                         | Vincule cada evento a las llamadas de retorno de progreso reales del reproductor (VAST hace esto por usted).        |
| `videoComplete` se dispara más de una vez                                          | El controlador de finalización también se dispara en bucle o reanudación.                   | Depure y limite a una sola finalización por reproducción.                                                           |
| `videoComplete` se dispara al cargar                                               | El evento de finalización está vinculado a la carga en lugar de al 100% de la reproducción. | Vincule `videoComplete` al final real de la reproducción.                                                           |

Para la solución de problemas generales de puntos de enlace, consulte la [Referencia técnica](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) sección de solución de problemas.

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