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

# Banner X videóinterakciós jelentések integrálása

## Mit kapcsol ez be

A videós jelentéskészítés megmutatja, meddig nézik a vásárlók a videót — kreatív anyag megtekintése, lejátszás, kvartilis haladás és befejezés —, valamint a vezérlési műveleteket (átugrás, szüneteltetés, némítás). A következőkre működik: Banner X videós kreatív anyag.

Banner X a videó általában egy VAST 4.0 lejátszón keresztül jelenik meg, amelyet Ön is integrált, így a jelentéskészítés engedélyezésének leggyorsabb módja, ha hagyja, hogy a lejátszó küldje el az eseményeket Ön helyett: Epsilon egy VAST címkét ad vissza a hirdetési válasz `adm` mezőjében, Ön pedig beilleszt egy `<TrackingEvents>` blokkot, amely az egyes lejátszási mérföldköveket az interakciós végpontra irányítja. Ez az útmutató bemutatja, hogyan építheti fel ezt a blokkot. Ha a lejátszója nem tud VAST nyomon követést kibocsátani (vagy a videót nem VAST-on keresztül szolgálják ki), használja helyette a [manuális jeladó tartalék megoldást](#alternative--fire-beacons-from-player-callbacks) .

Ez az útmutató csak a videós interakciótípusokat tárgyalja, és azt, hogyan kapcsolhatja össze őket a VAST-on keresztül. A végponttal, az hitelesítéssel, a fő mezőkkel, a jeladó működésével, a deduplikációval és a teszteléssel kapcsolatban lásd a [**Műszaki referencia**](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference).

## Előfeltételek

| Előfeltétel                                                                                                                               | Miért számít                                                                                                                                             |
| ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Olvassa el a következőt: [Műszaki referencia](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) | Lefedi az összes videóesemény által használt végpontot, hitelesítést, alapvető mezőket és deduplikációs szabályokat.                                     |
| A kiszolgált hirdetések egy megvalósult `adId` (`citrusAdId`)                                                                             | Biztosítja, hogy minden videós interakció visszakövethető legyen a kézbesített hirdetéshez.                                                              |
| Egy VAST 4.0-ra képes lejátszó, amely megjeleníti a `adm` címkét és elküldi a következőt: `<TrackingEvents>`                              | A lejátszó a tényleges lejátszási haladáskor küldi el a beillesztett jeladókat.                                                                          |
| A lejátszó kibővíti a VAST makrókat (pl. `[TIMESTAMP]`, `[CACHEBUSTING]`)                                                                 | Lehetővé teszi a lejátszó számára, hogy minden jeladót a küldés időpontjában bélyegezzen meg ahelyett, hogy Ön következtetne rá.                         |
| Elolvassa a következőt: `UniversalAdId` `idValue` minden egyes `<Creative>`                                                               | Ez a stabil, videónkénti azonosító Epsilon ezt használja mint `videoId` hogy összekapcsolja a tölcsért (egy hirdetés több videót is tartalmazhat).       |
| Konzisztens nyomonkövetési azonosító hirdetési munkamenetenként                                                                           | Használja a `sessionId`, `customerId`, or `dtmToken` értéket konzisztensen, hogy a jelentéskészítés összekapcsolhassa az eseményeket a munkamenet során. |

## Mit Epsilon szolgál ki ma (és mit ad hozzá Ön)

A(z) `adm` objektum a(z) Banner X válaszban egy VAST 4.0 címke. Epsilon már beépítette az **impresszió** és a **kattintás** nyomon követését (`<Impression>` és `<VideoClicks><ClickTracking>`). **Nem** szolgálja ki a haladási és interakciós nyomon követést — ezt Ön illeszti be.

Az interakciós végpont már elfogadja az alábbi összes videótípust. A kettőt úgy hidalhatja át, hogy hozzáad egy `<TrackingEvents>` blokkot, amelynek URL-jei `GET /v1/events/ad/interaction` jeladók. Amikor a lejátszó átlépi az egyes mérföldköveket, elküldi a megfelelő URL-t. Hagyja a Epsilonáltal kiszolgált `<Impression>` és `<ClickTracking>` csomópontokat pontosan úgy, ahogy vannak — Ön csak **hozzáad** `<TrackingEvents>`.

## Interakciótípusok videós jelentéskészítéshez

Küldje el az alapvető mezőket, valamint a következőt: `videoId` minden videóeseménynél. `iabConsentString` az opcionális mező minden típusnál (URL-kódolt). Küldje el a tölcséreseményeket sorrendben, ahogy a lejátszó eléri az egyes mérföldköveket, újra felhasználva ugyanazt a következőt: `adId`, `videoId`és nyomonkövetési azonosítót az egész megtekintési munkamenetben.

### Tölcséresemények

| `interactionType`    | Mikor kell elküldeni                                                                                    | Jelentéskészítési cél                                                      |
| -------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `videoCreativeView`  | Első renderelt videóképkocka                                                                            | Videóimpresszió kiindulópontja                                             |
| `videoPlay`          | A lejátszás elindul (felhasználó által kezdeményezett vagy automatikus lejátszás az irányelvek szerint) | Videóelindítási arány                                                      |
| `videoFirstQuartile` | A időtartam 25%-a megtekintve                                                                           | Videótölcsér Q1                                                            |
| `videoMidpoint`      | 50% megtekintve                                                                                         | Videótölcsér Q2                                                            |
| `videoThirdQuartile` | 75% megtekintve                                                                                         | Videótölcsér Q3                                                            |
| `videoComplete`      | 100% megtekintve                                                                                        | Befejezési arány — kreatív anyag hatékonysága és a videós költés igazolása |

### Vezérlési események

| `interactionType` | Mikor kell elküldeni                         | Jelentéskészítési cél                                                   |
| ----------------- | -------------------------------------------- | ----------------------------------------------------------------------- |
| `videoSkip`       | A felhasználó átugorja a befejezés előtt     | Átugrási arány — lemorzsolódás / kreatív anyaggal kapcsolatos problémák |
| `videoPause`      | A felhasználó szünetelteti                   | Elköteleződés mélysége / figyelemelterelés                              |
| `videoResume`     | A felhasználó folytatja a szüneteltetés után | Ismételt elköteleződés a szüneteltetés után                             |
| `videoMute`       | A felhasználó némítja a hangot               | Hangos elköteleződési preferencia                                       |
| `videoUnmute`     | A felhasználó visszahangosítja               | Aktív érdeklődés a hang iránt                                           |

## Rendelje a VAST-eseményeket a következkezőkhöz: Epsilon interakciótípusok

A VAST-lejátszók szabványos `<Tracking event="…">` visszahívásokat váltanak ki. Szúrjon be egy `<Tracking>` csomópontot az alábbi soronként, az leképezett interakciós végpontra mutatva `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`             |

Egyéb VAST-események, amelyeket fent nem említettünk (pl. `progress`, `fullscreen`, `exitFullscreen`, `rewind`, `close`) nem képezik a részét a Epsilon videós jelentéseknek — ne szúrjon be jeladókat ezekhez.

## Építse fel a követési URL-t

Minden beszúrt `<Tracking>` URL egyetlen, URL-kódolt `GET` jeladó. Töltse fel a felépítés során a hirdetési válaszból származó értékekkel, és használjon VAST-makrót az időbélyegzőhöz, hogy a lejátszó a kiváltáskor bélyegezze meg.

```
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` — olvassa be `citrusAdId` a kiszolgált bannerből.
* `videoId` — olvassa be `idValue` a következőtől: `<UniversalAdId>` a bekötendő kreatív anyagból. Ez kreatív anyagonként értendő: ha egy hirdetés több videót tartalmaz, mindegyik `<Creative>` megkapja a saját `<TrackingEvents>` blokkját **annak** a kreatív anyagnak a felhasználásával `idValue`, így a tölcsér visszamutathat a ténylegesen megtekintett videóra.
* `sessionId` — szúrja be a saját `sessionId` (or `customerId` / `dtmToken`) elemet a felépítéskor; a végpont visszautasítja a követési azonosító nélküli eseményeket.
* `timestamp` — használja a `[TIMESTAMP]` VAST-makrót, hogy a lejátszó a valós ISO 8601 szerinti kiváltási idővel helyettesítse azt. Ha a lejátszód nem támogatja, bélyegezze meg a jeladót más módon, de ne kódoljon be egyetlen fix időpontot az összes eseményhez.
* Adja hozzá a következőt: `[CACHEBUSTING]` eldobható paraméterként, ha a lejátszód gyorsítótárazza az azonos URL-eket.

## Szúrja be a következőt: `<TrackingEvents>` a kiszolgált VAST-címkébe

Adjon hozzá egy `<TrackingEvents>` blokkot mindegyik elem belsejében `<Creative>`'s `<Linear>` elemben (a köv. után: `<VideoClicks>`, megfelelve a VAST 4.0 mintának). Alább a következők: `<Impression>` és `<ClickTracking>` a következőkkel vannak kiszolgálva: Epsilon-kiszolgáltak és érintetlenek maradnak; a kiemelt `<TrackingEvents>` blokk az, amit Ön hozzáad. Vegye figyelembe, `videoId` újra felhasználja ennek a kreatív anyagnak a `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" %}
**Több videó egy hirdetésben** Ismételje meg a következőt: `<TrackingEvents>` blokkot minden egyes `<Creative>`esetében, mindegyik a sajátját használva: `UniversalAdId` `idValue` as `videoId`. **Soha ne osszon meg egyetlen `idValue`** elemét a kreatív anyagok között — ez teszi lehetővé, hogy a következők:\*\* Epsilon tulajdonítsák a tölcsért a kiszolgált konkrét videónak.\*\*
{% endhint %}

## Lefogási sorrend

A tölcséresemények ezt a sorrendet követik a teljes megtekintés során:

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

| Szabály                 | Útmutató                                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tölcsér mérföldkövei    | A tényleges lejátszási haladáshoz kell kötni. A VAST-lejátszók a valódi haladáskor váltják ki a kvartiliseket; ne szintetizálja őket tekeréskor.  |
| Vezérlési események     | `videoSkip`, `videoPause`, `videoResume`, `videoMute`, és a következők: `videoUnmute` bármelyik ponton kiválthatók a lejátszás során.             |
| Munkamenet-tulajdonítás | Használja újra ugyanazt a(z) `adId`, `videoId` (`idValue`), és a nyomon követési azonosítót a munkamenet során, hogy a tölcsér összekapcsolódjon. |

## Alternatíva — jeltovábbítók (beacons) indítása a lejátszó visszahívásaiból (callbacks)

Ha a lejátszója nem tud VAST-ot kibocsátani `<TrackingEvents>`, vagy a videót nem a VAST-on keresztül szolgálják ki, indítsa el ugyanazokat a jeltovábbítókat közvetlenül a lejátszó visszahívásaiból. A végpont és a mezők megegyeznek — csak a kódban hozza létre az URL-t a VAST-címke helyett.

### 1. lépés — A kontextus rögzítése

Olvassa el a(z) `adId` (`citrusAdId`) és a Kreatív anyag `UniversalAdId` `idValue` értékét, hogy ezt használja: `videoId`. Használja újra a munkamenet nyomon követési azonosítóját.

### 2. lépés — A tölcsér mérföldköveinek indítása a lejátszó visszahívásaiból

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

### 3. lépés — Vezérlési események indítása azok bekövetkeztekor

Kapcsolja be a kihagyás/szüneteltetés/folytatás/némítás/visszahangosítás funkciókat, és indítsa el a megfelelő típust. Csökkentse a gyors váltások gyakoriságát (debounce).

## Minta kérések

A beillesztett VAST URL-ek és a manuális jeltovábbítók ugyanarra a(z) `GET` kérésre futnak le. Az alábbi teljes URL-ek az olvashatóság érdekében sorokra vannak bontva — egyetlen kódolt lekérdezési karaktersorozatként (query string) küldje el azokat.

### Videó lejátszása

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

### Kvartilis mérföldkő

Ugyanaz a forma a(z) `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
```

### Vezérlési esemény

Ugyanaz a forma a(z) `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
```

## Hogyan néz ki a helyes működés

| Terület                     | Elvárt eredmény                                                                                                                         |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Beillesztett nyomon követés | Mindegyik `<Creative>` tartalmaz egy `<TrackingEvents>` blokkot; minden `<Tracking>` URL az adott Kreatív anyag `idValue` as `videoId`. |
| Kvartilis események         | A kvartilisek sorrendben érkeznek, pontosan egy `videoComplete` értékkel a teljes megtekintéshez.                                       |
| Vezérlési események         | Az események nem duplázódnak az adatduplikáció-szűrési szabályokon túl.                                                                 |
| Újramegtekintések           | Az ugyanabban a munkamenetben történő újramegtekintések újra használják a(z) `videoId` értékét, és hozzárendelhetők maradnak.           |

## Hibaelhárítás (Videóspecifikus részletek)

| Probléma                                                                                | Valószínű ok                                                                     | Teendő                                                                                                                                                   |
| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nem érkeznek előrehaladási események, csak megjelenés/kattintás                         | `<TrackingEvents>` nincs beillesztve, vagy azon kívül lett hozzáadva `<Linear>`. | Adja hozzá a blokkot mindegyik belsejében `<Creative>`'s `<Linear>` és erősítse meg, hogy a lejátszó értelmezi azt.                                      |
| Minden esemény egyetlen időbélyegzőn osztozik                                           | `[TIMESTAMP]` a makrót nem bontotta ki a lejátszó.                               | Erősítse meg a makrótámogatást, vagy bélyegezzen kiváltásonként; ne kódoljon be egyetlen időpontot.                                                      |
| Az események beérkeznek, de nem rendelhetők videóhoz                                    | `videoId` hiányzik, vagy újra fel lett használva a kreatív anyagok között.       | Állítsa be a következőt: `videoId` minden kreatív anyag saját `UniversalAdId` `idValue`.                                                                 |
| Az események HTTP 400 hibával térnek vissza                                             | Nem kódolt URL, hiányzó tracking id, vagy ismeretlen `interactionType`.          | Kódolja URL-ként a teljes `<Tracking>` URL-t; tartalmazza a következőt: `sessionId`/`customerId`/`dtmToken`; a pontosan feltérképezett típust használja. |
| Az események rögzített időközönként jelennek meg a lejátszásnak való megfelelés helyett | A jelzők időzítő alapján váltódnak ki a valódi előrehaladás helyett.             | Kösse az egyes eseményeket a lejátszó tényleges előrehaladási visszahívásaihoz (a VAST ezt elvégzi Ön helyett).                                          |
| `videoComplete` többször váltódik ki                                                    | A befejezési kezelő hurok vagy újrajátszás esetén is kiváltódik.                 | Szüntesse meg a prellést, és korlátozza lejátszásonként egyetlen befejezésre.                                                                            |
| `videoComplete` betöltéskor váltódik ki                                                 | A befejezési esemény a betöltéshez van kötve a 100%-os lejátszás helyett.        | Kösse a következőt: `videoComplete` a valódi lejátszás végéhez.                                                                                          |

Az végpontok általános hibaelhárításához lásd a [Műszaki referencia](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) hibaelhárítás szakaszt.

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