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

# Integrovať hlásenie interakcií s videom pre Banner X

## Čo sa týmto zapne

Reportovanie videa zobrazuje, do akej miery si kupujúci video pozrú — zobrazenie reklamného materiálu, prehratie, pokrok po kvartiloch a dokončenie — plus ovládacie akcie (preskočenie, pozastavenie, stlmenie). Funguje to pre Banner X video reklamný materiál.

Banner X video sa zvyčajne zobrazuje prostredníctvom prehrávača VAST 4.0, ktorý máte tiež integrovaný, takže najrýchlejší spôsob, ako povoliť toto reportovanie, je nechať prehrávač spúšťať udalosti za vás: Epsilon vracia značku VAST v `adm` poli odpovede na reklamu a vy vložíte `<TrackingEvents>` blok, ktorý smeruje každý míľnik prehrávania na koncový bod interakcie. Táto príručka ukazuje, ako tento blok vybudovať. Ak váš prehrávač nedokáže vysielať sledovanie VAST (alebo sa video nepodáva prostredníctvom VAST), použite [manuálnu zálohu majáka](#alternative--fire-beacons-from-player-callbacks) namiesto toho.

Táto príručka sa zaoberá iba typmi interakcií s videom a tým, ako ich prepojiť cez VAST. Pre koncový bod, autentifikáciu, základné polia, mechaniku majákov, dedup a testovanie si pozrite [**Technická príručka**](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference).

## Predpoklady

| Predpoklad                                                                                                                     | Prečo na tom záleží                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Prečítajte si [Technická príručka](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) | Pokrýva koncový bod, autentifikáciu, základné polia a pravidlá deduplikácie používané všetkými udalosťami videa.                              |
| Doručené reklamy vracajú realizované `adId` (`citrusAdId`)                                                                     | Zabezpečuje, že každá interakcia s videom môže byť priradená späť k doručenej reklame.                                                        |
| Prehrávač schopný VAST 4.0, ktorý zobrazuje `adm` značku a spúšťa `<TrackingEvents>`                                           | Prehrávač spúšťa vložené majáky pri reálnom pokroku prehrávania.                                                                              |
| Prehrávač rozširuje makrá VAST (napr. `[TIMESTAMP]`, `[CACHEBUSTING]`)                                                         | Umožňuje prehrávaču označiť každý maják v čase spustenia namiesto toho, aby ste to odvádzali vy.                                              |
| Prečítajte si `UniversalAdId` `idValue` z každého `<Creative>`                                                                 | Toto je stabilné ID pre jedno video, Epsilon používa ako `videoId` na prepojenie lievika (jedna reklama môže obsahovať viac ako jedno video). |
| Konzistentné sledovacie ID pre reláciu reklamy                                                                                 | Použite `sessionId`, `customerId`, or `dtmToken` konzistentne, aby reportovanie mohlo spájať udalosti naprieč reláciou.                       |

## Čo Epsilon doručuje dnes (a čo pridáte)

The `adm` objekt v Banner X odpovedi je značka VAST 4.0. Epsilon už do nej zapája sledovanie **impresií** a **klikov** (`<Impression>` a `<VideoClicks><ClickTracking>`). **Nepodáva** sledovanie pokroku a interakcií — to je to, čo vkladáte vy.

Koncový bod interakcie už prijíma každý typ videa nižšie. Tieto dva premostíte pridaním `<TrackingEvents>` bloku, ktorého adresy URL sú `GET /v1/events/ad/interaction` majáky. Keď prehrávač prekročí každý míľnik, spustí zodpovedajúcu adresu URL. Ponechajte Epsilon-podávané `<Impression>` a `<ClickTracking>` uzly presne tak, ako sú — iba **pridávate** `<TrackingEvents>`.

## Typy interakcií pre reportovanie videa

Odosielajte základné polia plus `videoId` pri každej udalosti videa. `iabConsentString` je voliteľné pole pri všetkých typoch (zakódované v URL). Spúšťajte udalosti lievika v poradí, ako prehrávač dosahuje každý míľnik, a znova použite rovnaké `adId`, `videoId`a sledovacie ID pre celú reláciu sledovania.

### Udalosti lievika

| `interactionType`    | Kedy spustiť                                                                                | Účel reportovania                                                                  |
| -------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `videoCreativeView`  | Prvý zobrazený snímok videa                                                                 | Základná línia impresie videa                                                      |
| `videoPlay`          | Prehrávanie sa začína (spustené používateľom alebo automatické prehrávanie podľa pravidiel) | Miera spustenia videa                                                              |
| `videoFirstQuartile` | Pozretých 25 % dĺžky                                                                        | Lievik videa Q1                                                                    |
| `videoMidpoint`      | Pozretých 50 %                                                                              | Lievik videa Q2                                                                    |
| `videoThirdQuartile` | Pozretých 75 %                                                                              | Lievik videa Q3                                                                    |
| `videoComplete`      | Pozretých 100 %                                                                             | Miera dokončenia — efektivita reklamného materiálu a odôvodnenie výdavkov na video |

### Udalosti ovládania

| `interactionType` | Kedy spustiť                                 | Účel reportovania                                            |
| ----------------- | -------------------------------------------- | ------------------------------------------------------------ |
| `videoSkip`       | Používateľ preskočí pred dokončením          | Miera preskočenia — pokles / problémy s reklamným materiálom |
| `videoPause`      | Používateľ pozastaví prehravanie             | Hĺbka zapojenia / rozptýlenie                                |
| `videoResume`     | Používateľ obnoví prehrávanie po pozastavení | Opätovné zapojenie po pozastavení                            |
| `videoMute`       | Používateľ stlmí zvuk                        | Preferencia zapojenia zvuku                                  |
| `videoUnmute`     | Používateľ zapne zvuk                        | Aktívny záujem o zvuk                                        |

## Mapovať udalosti VAST na Epsilon typy interakcií

VAST prehrávače spúšťajú štandardné `<Tracking event="…">` spätné volania. Vložte jeden `<Tracking>` uzol na každý riadok nižšie, ukazujúci na koncový bod interakcie s namapovanou `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`             |

Ostatné udalosti VAST, ktoré nie sú spomenuté vyššie (napr. `progress`, `fullscreen`, `exitFullscreen`, `rewind`, `close`) nie sú súčasťou Epsilon reportingu videa — nevkladajte pre ne majáky.

## Zostavte sledovaciu URL

Každá vložená `<Tracking>` URL je jediný maják s kódovaním `GET` URL. Naplňte ho pri zostavovaní hodnotami z odpovede na reklamu a použite makro VAST pre časovú pečiatku, aby ju prehrávač opečiatkoval v čase spustenia.

```
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` — prečítajte z `citrusAdId` dodaného bannera.
* `videoId` — prečítajte z `idValue` z `<UniversalAdId>` reklamného materiálu, ktorý zapájate. Toto je pre každý reklamný materiál osobitne: ak reklama obsahuje viacero videí, každé `<Creative>` dostane svoj vlastný `<TrackingEvents>` blok pomocou **daného** reklamného materiálu `idValue`, takže lievik sa prepojí späť s videom, ktoré bolo skutočne pozreté.
* `sessionId` — vložte svoj `sessionId` (or `customerId` / `dtmToken`) pri zostavovaní; koncový bod odmieta udalosti bez ID sledovania.
* `timestamp` — použite `[TIMESTAMP]` makro VAST, aby prehrávač nahradil skutočný čas spustenia vo formáte ISO 8601. Ak váš prehrávač toto nepodporuje, opečiatkujte maják iným spôsobom, ale nenastavujte pevne jeden čas pre všetky udalosti.
* Pridať `[CACHEBUSTING]` ako pomocný parameter, ak váš prehrávač ukladá identické URL do vyrovnávacej pamäte.

## Vložte `<TrackingEvents>` do doručenej značky VAST

Pridajte `<TrackingEvents>` blok do každého `<Creative>`'s `<Linear>` prvku (po `<VideoClicks>`, zodpovedajúci vzorke VAST 4.0). Nižšie sú `<Impression>` a `<ClickTracking>` doručené cez Epsilona ponechané bez zmeny; zvýraznený `<TrackingEvents>` blok je to, čo pridávate. Všimnite si, `videoId` znova používa tento reklamný materiál `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" %}
**Viacero videí v jednej reklame** Zopakujte `<TrackingEvents>` blok pre každý `<Creative>`, pričom každý používa svoj vlastný `UniversalAdId` `idValue` as `videoId`. **Nikdy nezdieľajte jeden `idValue`** naprieč reklamnými materiálmi — to je to, čo umožňuje Epsilon pripísať lievik konkrétnemu doručenému videu.\*\*
{% endhint %}

## Sekvencia prehrávania

Udalosti lievika nasledujú toto poradie počas celého zobrazenia:

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

| Pravidlo           | Usmernenie                                                                                                                                            |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Míľniky lievika    | Musia byť prepojené so skutočným priebehom prehrávania. VAST prehrávače spúšťajú kvartily pri skutočnom posune; nevytvárajte ich umelo pri pretáčaní. |
| Udalosti ovládania | `videoSkip`, `videoPause`, `videoResume`, `videoMute`, a `videoUnmute` sa môžu spustiť v ktoromkoľvek bode počas prehrávania.                         |
| Atribúcia relácie  | Znova použite ten istý `adId`, `videoId` (`idValue`), a ID sledovania v rámci relácie, aby sa lievik prepojil.                                        |

## Alternatíva — spúšťajte majáky zo spätných volaní prehrávača

Ak váš prehrávač nemôže vysielať VAST `<TrackingEvents>`, alebo sa video neposkytuje cez VAST, spusťte rovnaké majáky priamo zo spätných volaní prehrávača. Koncový bod a polia sú identické — iba vytvárate URL v kóde namiesto vo značke VAST.

### Krok 1 — Zachyťte kontext

Prečítajte si `adId` (`citrusAdId`) a reklamného materiálu `UniversalAdId` `idValue` na použitie ako `videoId`. Znova použite ID sledovania relácie.

### Krok 2 — Spúšťajte míľniky lievika zo spätných volaní prehrávača

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

### Krok 3 — Spúšťajte riadiace udalosti tak, ako k nim dochádza

Prepojte preskočenie/pozastavenie/obnovenie/stlmenie/zrušenie stlmenia a spusťte zodpovedajúci typ. Debouncujte rýchle prepínania.

## Ukážkové požiadavky

Vstreknuté URL VAST a manuálne majáky smerujú na rovnaký `GET` požiadavka. Úplné URL nižšie sú kvôli prehľadnosti zalomené — odosielajte ako jediný kódovaný dopytovací reťazec.

### Prehratie videa

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

### Míľnik kvartilu

Rovnaký tvar pre `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
```

### Riadiaca udalosť

Rovnaký tvar pre `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
```

## Ako vypadá dobrý výsledok

| Oblasť                | Očakávaný výsledok                                                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Vstreknuté sledovanie | Každý `<Creative>` nesie jeden `<TrackingEvents>` blok; každý `<Tracking>` URL používa daný reklamný materiál `idValue` as `videoId`. |
| Udalosti kvartilu     | Kvartily prichádzajú v poradí, s presne jedným `videoComplete` pre úplné pozretie.                                                    |
| Udalosti ovládania    | Udalosti sa neduplikujú nad rámec pravidiel deduplikácie.                                                                             |
| Opätovné pozretia     | Opätovné pozretia v rovnakej relácii znova používajú `videoId` a zostávajú priraditeľné.                                              |

## Riešenie problémov (špecifiká videa)

| Problém                                                                 | Pravdepodobná príčina                                                           | Riešenie                                                                                                       |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Neprichádzajú žiadne udalosti priebehu, iba zobrazenie/kliknutie        | `<TrackingEvents>` nie je vstreknuté, alebo bolo pridané mimo `<Linear>`.       | Pridajte blok do každého `<Creative>`'s `<Linear>` a potvrďte, že ho prehrávač spracováva.                     |
| Všetky udalosti zdieľajú jednu časovú pečiatku                          | `[TIMESTAMP]` makro nebolo rozšírené prehrávačom.                               | Potvrďte podporu makier alebo pečiatkujte pri každom spustení; nenastavujte jeden čas napevno.                 |
| Udalosti prichádzajú, ale nedajú sa priradiť k videu                    | `videoId` chýba alebo sa znova používa naprieč reklamnými materiálmi.           | Nastavte `videoId` pre vlastný reklamný materiál `UniversalAdId` `idValue`.                                    |
| Udalosti vracajú HTTP 400                                               | Nekódovaná URL, chýbajúce ID sledovania alebo neznámy `interactionType`.        | URL-zakódujte celú `<Tracking>` URL; zahrňte `sessionId`/`customerId`/`dtmToken`; použite presne mapovaný typ. |
| Udalosti sa zobrazujú v pevných intervaloch a nezodpovedajú prehrávaniu | Majáky sa spúšťajú na základe časovača namiesto skutočného priebehu.            | Naviažte každú udalosť na skutočné spätné volania priebehu prehrávača (VAST to urobí za vás).                  |
| `videoComplete` sa spúšťa viac ako raz                                  | Obslužná rutina dokončenia sa spúšťa aj pri slučke alebo opakovanom prehrávaní. | Debouncujte a obmedzte na jedno dokončenie na prehrávanie.                                                     |
| `videoComplete` sa spúšťa pri načítaní                                  | Udalosť dokončenia je spojená s načítaním namiesto 100 % prehratia.             | Naviažte `videoComplete` na skutočný koniec prehrávania.                                                       |

Všeobecné riešenie problémov s koncovým bodom nájdete v [Technická príručka](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) sekcii riešenia problémov.

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