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

# Integrace hlášení interakce s videem Banner X

## Co tato funkce zapíná

Hlášení pro video zobrazuje, jak daleko nakupující sledovali — zobrazení reklamního materiálu, přehrání, průběh po kvartilech a dokončení — a také ovládací akce (přeskočení, pozastavení, ztlumení). Funguje pro Banner X videoreklamní materiál.

Banner X video je obvykle vykreslováno prostřednictvím přehrávače VAST 4.0, který máte rovněž integrovaný, takže nejrychlejším způsobem, jak toto hlášení povolit, je nechat přehrávač odesílat události za vás: Epsilon vrací tag VAST v `adm` poli odpovědi na reklamu a vy vložíte `<TrackingEvents>` blok, který odkazuje každý milník přehrávání na koncový bod interakce. Tato příručka ukazuje, jak tento blok sestavit. Pokud váš přehrávač nedokáže vysílat sledování VAST (nebo video není poskytováno prostřednictvím VAST), použijte [záložní řešení s manuálním majákem](#alternative--fire-beacons-from-player-callbacks) místo toho.

Tato příručka se zabývá pouze typy interakcí s videem a způsobem jejich zapojení přes VAST. Informace o koncovém bodu, autentizaci, základních polích, mechanice majáků, deduplikaci a testování naleznete v [**Technická reference**](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference).

## Předpoklady

| Předpoklad                                                                                                                    | Proč na tom záleží                                                                                                                                                          |
| ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Přečtěte si [Technická reference](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) | Zahrnuje koncový bod, autentizaci, základní pole a pravidla deduplikace používaná všemi událostmi videa.                                                                    |
| Doručené reklamy vracejí realizované `adId` (`citrusAdId`)                                                                    | Zajišťuje, že každou interakci s videem lze zpětně připsat doručené reklamě.                                                                                                |
| Přehrávač podporující VAST 4.0, který vykresluje `adm` tag a odesílá `<TrackingEvents>`                                       | Přehrávač odesílá vložené majáky při reálném průběhu přehrávání.                                                                                                            |
| Přehrávač rozbaluje makra VAST (např. `[TIMESTAMP]`, `[CACHEBUSTING]`)                                                        | Umožňuje přehrávači opatřit každý maják razítkem v čase odeslání, místo abyste to odvozovali vy.                                                                            |
| Čtete `UniversalAdId` `idValue` z každého `<Creative>`                                                                        | Jedná se o stabilní ID pro jedno video, které Epsilon používá jako `videoId` k propojení celého konverzního trychtýře (jediná reklama může obsahovat více než jedno video). |
| Konzistentní ID sledování pro relaci reklamy                                                                                  | Použijte `sessionId`, `customerId`, or `dtmToken` konzistentně, aby výkaznictví molo propojit události napříč relací.                                                       |

## Co Epsilon dnes zobrazuje (a co přidáte)

Objekt `adm` v objektu Banner X odpověď je tag VAST 4.0. Epsilon již do něj zapojuje sledování **zobrazení** a **kliknutí** (`<Impression>` a `<VideoClicks><ClickTracking>`). **Nezobrazuje** však sledování průběhu a interakce — to je to, co vložíte vy.

Koncový bod pro interakce již přijímá každý níže uvedený typ videa. Tyto dva propojíte přidáním bloku `<TrackingEvents>` , jehož URL adresy jsou `GET /v1/events/ad/interaction` maáčky. Když přehrávač překročí každý milník, spustí odpovídající URL. Ponechte uzly Epsilonservírované pomocí `<Impression>` a `<ClickTracking>` přesně tak, jak jsou — pouze **přidáváte** `<TrackingEvents>`.

## Typy interakcí pro výkaznictví videa

Odesílejte základní pole plus `videoId` při každé události videa. `iabConsentString` je volitelné pole u všech typů (s kódováním URL). Události konverzního trychtýře spouštějte v pořadí, jak přehrávač dosahuje jednotlivých milníků, a znovu použijte stejné `adId`, `videoId`a ID sledování pro celou relaci zobrazení.

### Události konverzního trychtýře

| `interactionType`    | Kdy spustit                                                                      | Účel výkaznictví                                                            |
| -------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `videoCreativeView`  | Vykreslen první snímek videa                                                     | Základní linie zobrazení videa                                              |
| `videoPlay`          | Přehrávání začíná (spuštěno uživatelem nebo automatické přehrávání dle pravidel) | Míra spuštění videa                                                         |
| `videoFirstQuartile` | Sledováno 25 % délky                                                             | Video trychtýř Q1                                                           |
| `videoMidpoint`      | Sledováno 50 %                                                                   | Video trychtýř Q2                                                           |
| `videoThirdQuartile` | Sledováno 75 %                                                                   | Video trychtýř Q3                                                           |
| `videoComplete`      | Sledováno 100 %                                                                  | Míra dokončení — účinnost reklamního materiálu a odůvodnění výdajů za video |

### KONTROLNÍ UDÁLOSTI

| `interactionType` | Kdy spustit                               | Účel výkaznictví                                             |
| ----------------- | ----------------------------------------- | ------------------------------------------------------------ |
| `videoSkip`       | Uživatel přeskočí před dokončením         | Míra přeskočení — opuštění / problémy s reklamním materiálem |
| `videoPause`      | Uživatel pozastaví                        | Hloubka zapojení / rozptýlení                                |
| `videoResume`     | Uživatel obnoví přehrávání po pozastavení | Opětovné zapojení po pozastavení                             |
| `videoMute`       | Uživatel ztlumí zvuk                      | Preference zapojení zvuku                                    |
| `videoUnmute`     | Uživatel zapne zvuk                       | Aktivní zájem o zvuk                                         |

## Mapování událostí VAST na Epsilon typy interakce

Přehrávače VAST spouštějí standardní `<Tracking event="…">` zpětná volání. Vložte jeden `<Tracking>` uzel na řádek níže, ukazující na koncový bod interakce s namapovanou hodnotou `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í události VAST, které nejsou zmíněny výše (např. `progress`, `fullscreen`, `exitFullscreen`, `rewind`, `close`), nejsou součástí Epsilon reportování videa — nevkládejte pro ně majáky.

## Sestavte sledovací URL

Každá vložená `<Tracking>` URL je jediný maják kódovaný v `GET` URL. Vyplňte jej při sestavování hodnotami z odpovědi na reklamu a použijte makro VAST pro časové razítko, aby jej přehrávač orazítkoval v čase spuštění.

```
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` — přečtěte z `citrusAdId` dodaného banneru.
* `videoId` — přečtěte z `idValue` z `<UniversalAdId>` reklamního materiálu, který zapojujete. Toto je pro každý reklamní materiál: pokud reklama obsahuje více videí, každé `<Creative>` získá svůj vlastní `<TrackingEvents>` blok s použitím `idValue`daniho reklamního materiálu, takže se konverzní trychtýř propojí s videem, které bylo skutečně zhlédnuto.
* `sessionId` — vložte svůj `sessionId` (or `customerId` / `dtmToken`) při sestavování; koncový bod odmítne události bez ID sledování.
* `timestamp` — použijte makro `[TIMESTAMP]` VAST, aby přehrávač nahradil skutečný čas spuštění ve formátu ISO 8601. Pokud to váš přehrávač nepodporuje, orazítkujte maják jiným způsobem, ale nenastavujte pevně jeden čas pro všechny události.
* Přidejte `[CACHEBUSTING]` jako odkládací parametr, pokud váš přehrávač ukládá identické URL do mezipaměti.

## Vložte `<TrackingEvents>` do servírované značky VAST

Přidejte `<TrackingEvents>` blok uvnitř každého `<Creative>`'s `<Linear>` prvku (po `<VideoClicks>`, což odpovídá vzorku VAST 4.0). Níže jsou `<Impression>` a `<ClickTracking>` servírovány z Epsilona ponechány beze změny; zvýrazněný `<TrackingEvents>` blok je to, co přidáte. Všimněte si, `videoId` znovu používá 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" %}
**Více videí v jedné reklamě** Opakujte `<TrackingEvents>` blok pro každý `<Creative>`, přičemž každý používá svůj vlastní `UniversalAdId` `idValue` as `videoId`. **Nikdy nesdílejte jeden `idValue`** napříč reklamními materiály — to je to, co umožňuje Epsilon přiřadit konverzní trychtýř ke konkrétnímu servírovanému videu.\*\*
{% endhint %}

## Sekvence přehrávání

Události konverzního trychtýře sledují toto pořadí během celého zhlédnutí:

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

| Pravidlo                      | Pokyny                                                                                                                                          |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Milníky konverzního trychtýře | Musí být propojeny se skutečným průběhem přehrávání. Přehrávače VAST spouštějí kvartily při skutečném průběhu; nesyntetizujte je při přetáčení. |
| Kontrolní události            | `videoSkip`, `videoPause`, `videoResume`, `videoMute`, a `videoUnmute` se mohou spustit v kterémkoli bodě během přehrávání.                     |
| Atributace relace             | Znovu použijte stejný `adId`, `videoId` (`idValue`), a ID sledování v rámci relace, aby se trychtýř propojal.                                   |

## Alternativa — spouštění majáků z zpětných volání přehrávače

Pokud váš přehrávač nemůže vygenerovat VAST `<TrackingEvents>`, nebo video není poskytováno prostřednictvím VAST, spusťte stejné majáky přímo ze zpětných volání přehrávače. Koncový bod a pole jsou identické — pouze vytváříte URL v kódu namísto v značce VAST.

### Krok 1 — Zachycení kontextu

Přečtěte si `adId` (`citrusAdId`) a reklamního materiálu `UniversalAdId` `idValue` pro použití jako `videoId`. Znovu použijte ID sledování relace.

### Krok 2 — Spuštění milníků trychtýře ze zpětných volání přehrávače

```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 — Spuštění ovládacích událostí, jak k nim dochází

Propojte přeskočení/pozastavení/obnovení/ztišení/zrušení ztišení a spusťte odpovídající typ. Omezte rychlé přepínání.

## Ukázkové požadavky

Vložené VAST URL a manuální majáky se vyhodnocují na stejný `GET` požadavek. Úplné URL níže jsou pro přehlednost zalamovány — odešlete jako jediný zakódovaný dotazovací řetězec.

### Přehrání 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
```

### Milník kvartilu

Stejný tvar pro `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
```

### Ovládací událost

Stejný tvar pro `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
```

## Jak vypadá správný výsledek

| Oblast              | Očekávaný výsledek                                                                                                                        |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Vložené sledování   | Každý `<Creative>` nese jeden `<TrackingEvents>` blok; každá `<Tracking>` URL používá daného reklamního materiálu `idValue` as `videoId`. |
| Události kvartilu   | Kvartily přicházejí v pořadí, s přesně jedním `videoComplete` pro úplné zhlédnutí.                                                        |
| Kontrolní události  | Události se neduplikují nad rámec pravidel deduplikace.                                                                                   |
| Opakovaná zhlédnutí | Opakovaná zhlédnutí ve stejné relaci znovu používají `videoId` a zůstávají přiřaditelná.                                                  |

## Řešení problémů (specifika videa)

| Problém                                                              | Pravděpodobná příčina                                                            | Akce                                                                                                           |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Nepřicházejí žádné události průběhu, pouze zobrazení/kliknutí        | `<TrackingEvents>` nebylo vloženo nebo bylo přidáno mimo `<Linear>`.             | Přidejte blok do každého `<Creative>`'s `<Linear>` a potvrďte, že jej přehrávač zpracuje.                      |
| Všechny události sdílejí jedno časové razítko                        | `[TIMESTAMP]` makro nebylo přehrávačem rozbaleno.                                | Potvrďte podporu maker nebo přidejte razítko při každém spuštění; neukládejte jeden čas natvrdo.               |
| Události dorazí, ale nelze je přiřadit k videu                       | `videoId` chybí nebo je znovu použito napříč reklamními materiály.               | Nastavte `videoId` na vlastní reklamního materiálu `UniversalAdId` `idValue`.                                  |
| Události vracejí HTTP 400                                            | Nezakódovaná URL, chybějící ID sledování nebo neznámé `interactionType`.         | Kódujte celou URL `<Tracking>` URL; zahrňte `sessionId`/`customerId`/`dtmToken`; použijte přesný mapovaný typ. |
| Události se zobrazují v pevných intervalech, nikoli podle přehrávání | Majáky spouštěné na základě časovače namísto skutečného průběhu.                 | Propojte každou událost se skutečnými zpětnými voláními průběhu přehrávače (VAST to udělá za vás).             |
| `videoComplete` se spustí více než jednou                            | Obslužná rutina dokončení se spouští také při smyčce nebo opakovaném přehrávání. | Omezte a zablokujte na jedno dokončení na jedno přehrání.                                                      |
| `videoComplete` se spustí při načtení                                | Událost dokončení je svázána s načtením spíše než se 100% přehráním.             | Propojte `videoComplete` se skutečným koncem přehrávání.                                                       |

Obecné řešení problémů s koncovými body naleznete v [Technická reference](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) sekci Řešení problémů.

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