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

# Integrar relatório de interação de vídeo do Banner X

## O que isso ativa

Os relatórios de vídeo mostram até onde os compradores assistem — visualização do criativo, reprodução, progresso por quartil e conclusão — além de ações de controle (pular, pausar, silenciar). Funciona para Banner X criativo de vídeo.

Banner X o vídeo é normalmente renderizado por meio de um reprodutor VAST 4.0 que você também integrou, portanto, a maneira mais rápida de ativar esse relatório é permitir que o reprodutor acione os eventos para você: Epsilon retorna uma tag VAST no campo `adm` da resposta do anúncio, e você injeta um bloco `<TrackingEvents>` que aponta cada marco de reprodução para o endpoint de interação. Este guia mostra como construir esse bloco. Se o seu reprodutor não puder emitir o rastreamento VAST (ou se o vídeo não for servido via VAST), use a [alternativa de beacon manual](#alternative--fire-beacons-from-player-callbacks) em vez disso.

Este guia cobre apenas os tipos de interação de vídeo e como conectá-los via VAST. Para o endpoint, autenticação, campos principais, mecânica de beacon, eliminação de duplicatas e testes, consulte a [**Referência técnica**](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference).

## Pré-requisitos

| Pré-requisito                                                                                                           | Por que isso importa                                                                                                              |
| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Leia a [Referência técnica](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) | Cobre o endpoint, autenticação, campos principais e regras de eliminação de duplicatas usadas por todos os eventos de vídeo.      |
| Os anúncios servidos retornam um `adId` (`citrusAdId`)                                                                  | Garante que cada interação de vídeo possa ser atribuída de volta ao anúncio entregue.                                             |
| Um reprodutor compatível com VAST 4.0 que renderiza a tag `adm` e aciona `<TrackingEvents>`                             | O reprodutor aciona os beacons injetados no progresso real da reprodução.                                                         |
| O reprodutor expande as macros VAST (por exemplo, `[TIMESTAMP]`, `[CACHEBUSTING]`)                                      | Permite que o reprodutor carimbe cada beacon no momento do acionamento, em vez de você inferi-lo.                                 |
| Você lê `UniversalAdId` `idValue` de cada `<Creative>`                                                                  | Este é o ID estável por vídeo que a Epsilon usa como `videoId` para unir o funil (um único anúncio pode conter mais de um vídeo). |
| ID de rastreamento consistente por sessão de anúncio                                                                    | Use `sessionId`, `customerId`, or `dtmToken` consistentemente para que os relatórios possam unir eventos em toda a sessão.        |

## O que a Epsilon serve hoje (e o que você adiciona)

O objeto `adm` na resposta Banner X é uma tag VAST 4.0. A Epsilon já conecta o rastreamento de **impressão** e **clique** nele (`<Impression>` e `<VideoClicks><ClickTracking>`). Ela **não** serve o rastreamento de progresso e interação — é isso que você injeta.

O endpoint de interação já aceita todos os tipos de vídeo abaixo. Você conecta os dois adicionando um bloco `<TrackingEvents>` cujas URLs são beacons da `GET /v1/events/ad/interaction` . Quando o reprodutor ultrapassa cada marco, ele aciona a URL correspondente. Deixe os nós Epsilonservidos pela `<Impression>` e `<ClickTracking>` exatamente como estão — você está apenas **adicionando** `<TrackingEvents>`.

## Tipos de interação para relatórios de vídeo

Envie os campos principais mais `videoId` em cada evento de vídeo. `iabConsentString` é o campo opcional em todos os tipos (codificado em URL). Acione eventos de funil em ordem conforme o reprodutor atinge cada marco, reutilizando o mesmo `adId`, `videoId`, e ID de rastreamento para toda a sessão de visualização.

### Eventos de funil

| `interactionType`    | Quando acionar                                                                                    | Objetivo do relatório                                                        |
| -------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `videoCreativeView`  | Primeiro quadro do vídeo renderizado                                                              | Linha de base de impressão do vídeo                                          |
| `videoPlay`          | A reprodução é iniciada (iniciada pelo usuário ou reprodução automática de acordo com a política) | Taxa de início do vídeo                                                      |
| `videoFirstQuartile` | 25% da duração assistida                                                                          | Funil de vídeo Q1                                                            |
| `videoMidpoint`      | 50% assistido                                                                                     | Funil de vídeo Q2                                                            |
| `videoThirdQuartile` | 75% assistido                                                                                     | Funil de vídeo Q3                                                            |
| `videoComplete`      | 100% assistido                                                                                    | Taxa de conclusão — eficácia do criativo e justificativa de gastos com vídeo |

### Eventos de Controle

| `interactionType` | Quando acionar                   | Objetivo do relatório                               |
| ----------------- | -------------------------------- | --------------------------------------------------- |
| `videoSkip`       | O usuário pula antes de concluir | Taxa de pular — desistência / problemas de criativo |
| `videoPause`      | O usuário pausa                  | Nível de engajamento / distração                    |
| `videoResume`     | O usuário retoma após a pausa    | Reengajamento após a pausa                          |
| `videoMute`       | O usuário desativa o áudio       | Preferência de engajamento de áudio                 |
| `videoUnmute`     | O usuário ativa o áudio          | Interesse ativo de áudio                            |

## Mapeie eventos VAST para Epsilon tipos de interação

Players VAST acionam callbacks `<Tracking event="…">` padrão. Injete um `<Tracking>` nó por linha abaixo, apontando para o endpoint de interação com o VAST 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`             |

Outros eventos VAST sem menção acima (ex.: `progress`, `fullscreen`, `exitFullscreen`, `rewind`, `close`) não fazem parte dos Epsilon relatórios de vídeo — não injete beacons para eles.

## Construa a URL de rastreamento

Cada URL `<Tracking>` injetada é um único beacon com `GET` URL-encoded. Preencha-a no momento do build com valores da resposta do anúncio e use uma macro VAST para o carimbo de data/hora para que o player a carimbe no momento do 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` — leia `citrusAdId` a partir do banner veiculado.
* `videoId` — leia `idValue` a partir do `<UniversalAdId>` do criativo que você está configurando. Isso é por criativo: se um anúncio contiver vários vídeos, cada `<Creative>` recebe seu próprio `<TrackingEvents>` bloco usando o `idValue`daquele **criativo**, para que o funil seja vinculado de volta ao vídeo que foi realmente assistido.
* `sessionId` — injete seu `sessionId` (or `customerId` / `dtmToken`) no momento do build; o endpoint rejeita eventos sem id de rastreamento.
* `timestamp` — use a macro `[TIMESTAMP]` VAST para que o player substitua pelo tempo real de disparo em ISO 8601. Se o seu player não der suporte a isso, carimbe o beacon de outra forma, mas não defina um horário único fixo para todos os eventos.
* Adicione `[CACHEBUSTING]` como um parâmetro descartável se o seu player fizer cache de URLs idênticas.

## Injete `<TrackingEvents>` no tag VAST veiculado

Adicione um `<TrackingEvents>` bloco dentro de cada `<Creative>`'s `<Linear>` elemento (após `<VideoClicks>`, correspondendo ao exemplo do VAST 4.0). Abaixo, os `<Impression>` e `<ClickTracking>` são Epsilonservidos e mantidos intactos; o bloco destacado `<TrackingEvents>` é o que você adiciona. Note que `videoId` reutiliza o deste criativo `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" %}
**Vários vídeos em um anúncio** Repita o `<TrackingEvents>` bloco para cada `<Creative>`, cada um usando seu próprio `UniversalAdId` `idValue` as `videoId`. **Nunca compartilhe um `idValue`** entre criativos — é isso que permite que\*\* Epsilon atribua o funil ao vídeo específico veiculado.\*\*
{% endhint %}

## Sequência de Reprodução

Eventos de funil seguem esta ordem ao longo de uma visualização completa:

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

| Regra                | Orientação                                                                                                                                    |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Marcos do funil      | Devem estar vinculados ao progresso real de reprodução. Players VAST acionam quartis no progresso genuíno; não os sintetize ao buscar (seek). |
| Eventos de controle  | `videoSkip`, `videoPause`, `videoResume`, `videoMute`, e `videoUnmute` podem ser acionados em qualquer ponto durante a reprodução.            |
| Atribuição de sessão | Reutilize o mesmo `adId`, `videoId` (`idValue`), e o id de rastreamento ao longo da sessão para que o funil se conecte.                       |

## Alternativa — disparar sinalizadores (beacons) a partir de retornos de chamada (callbacks) do player

Se o seu player não puder emitir VAST `<TrackingEvents>`, ou se o vídeo não for servido via VAST, dispare os mesmos sinalizadores (beacons) diretamente dos retornos de chamada (callbacks) do player. O ponto de extremidade (endpoint) e os campos são idênticos — você só está construindo a URL no código em vez da tag VAST.

### Passo 1 — Capturar contexto

Ler `adId` (`citrusAdId`) e do Criativo `UniversalAdId` `idValue` para usar como `videoId`. Reutilize o id de rastreamento da sessão.

### Passo 2 — Disparar marcos do funil a partir dos retornos de chamada (callbacks) do player

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

### Passo 3 — Disparar eventos de controle conforme eles acontecem

Conecte pular/pausar/retomar/mutar/desmutar e dispare o tipo correspondente. Evite disparos múltiplos e rápidos em alternâncias frequentes (debounce).

## Exemplos de solicitações

As URLs VAST injetadas e os sinalizadores (beacons) manuais resolvem para o mesmo `GET` solicitação. As URLs completas abaixo foram quebradas em linhas para facilitar a leitura — envie como uma única string de consulta codificada.

### Reprodução de vídeo

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

### Marco de quartil

Mesmo formato 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 controle

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

## Como deve ser

| Área                  | Resultado esperado                                                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Rastreamento injetado | Cada `<Creative>` carrega um `<TrackingEvents>` bloco; cada `<Tracking>` URL usa o desse Criativo `idValue` as `videoId`. |
| Eventos de quartil    | Os quartis chegam em ordem, com exatamente um `videoComplete` para uma visualização completa.                             |
| Eventos de controle   | Os eventos não se duplicam além das regras de desduplicação.                                                              |
| Novas visualizações   | Novas visualizações na mesma sessão reutilizam `videoId` e permanecem atribuíveis.                                        |

## Solução de problemas (especificidades de vídeo)

| Problema                                                                      | Causa provável                                                                     | Ação                                                                                                                                  |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Nenhum evento de progresso chega, apenas impressão/clique                     | `<TrackingEvents>` não injetado, ou adicionado fora de `<Linear>`.                 | Adicione o bloco dentro de cada `<Creative>`'s `<Linear>` e confirme que o player o analisa.                                          |
| Todos os eventos compartilham um carimbo de data/hora (timestamp)             | `[TIMESTAMP]` macro não expandida pelo player.                                     | Confirme o suporte à macro ou registre a data/hora a cada disparo; não defina um horário fixo no código.                              |
| Os eventos chegam, mas não podem ser atribuídos a um vídeo                    | `videoId` ausente ou reutilizado entre criativos.                                  | Defina `videoId` para o próprio de cada Criativo `UniversalAdId` `idValue`.                                                           |
| Os eventos retornam HTTP 400                                                  | URL não codificada, id de rastreamento ausente ou desconhecido `interactionType`.  | Codifique a URL inteira em formato URL-encode `<Tracking>` URL; inclua `sessionId`/`customerId`/`dtmToken`; use o tipo exato mapeado. |
| Os eventos aparecem em intervalos fixos em vez de corresponderem à reprodução | Sinalizadores (beacons) disparados por um temporizador em vez do progresso real.   | Vincule cada evento aos retornos de chamada (callbacks) de progresso reais do player (o VAST faz isso por você).                      |
| `videoComplete` dispara mais de uma vez                                       | O manipulador de conclusão também dispara no loop ou na repetição.                 | Aplique debounce e limite a uma única conclusão por reprodução.                                                                       |
| `videoComplete` dispara ao carregar                                           | O evento de conclusão está vinculado ao carregamento em vez de 100% da reprodução. | Vincule `videoComplete` ao final real da reprodução.                                                                                  |

Para solução de problemas gerais de endpoints, consulte a [Referência técnica](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) seção de solução 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/pt-br/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.