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

# Banner X Video-Interaktions-Meldung integrieren

## Was dadurch aktiviert wird

Das Video-Reporting zeigt, wie lange Shopper zusehen — Werbemittel-Aufruf, Wiedergabe, Quartilsfortschritt und Fertigstellung — sowie Steuerungsaktionen (Überspringen, Pause, Stummschalten). Es funktioniert für Banner X Video-Werbemittel.

Banner X Videos werden in der Regel über einen VAST 4.0-Player gerendert, den Sie ebenfalls integriert haben. Der schnellste Weg zur Aktivierung dieses Reportings besteht also darin, den Player die Ereignisse für Sie auslösen zu lassen: Epsilon gibt einen VAST-Tag im `adm` -Feld der Anzeigenantwort zurück, und Sie fügen einen `<TrackingEvents>` -Block ein, der jeden Wiedergabe-Meilenstein auf den Interaktions-Endpunkt verweist. Dieser Leitfaden zeigt, wie Sie diesen Block erstellen. Wenn Ihr Player kein VAST-Tracking ausgeben kann (oder das Video nicht über VAST bereitgestellt wird), verwenden Sie stattdessen die [manueller Beacon-Rückfall](#alternative--fire-beacons-from-player-callbacks) .

Dieser Leitfaden behandelt nur die Videointeraktionstypen und deren Einbindung über VAST. Informationen zum Endpunkt, zur Authentifizierung, zu den Kernfeldern, zur Beacon-Mechanik, zur Deduplizierung und zum Testen finden Sie in der [**Technische Referenz**](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference).

## Voraussetzungen

| Voraussetzung                                                                                                                   | Warum es wichtig ist                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Lesen Sie die [Technische Referenz](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) | Deckt den Endpunkt, die Authentifizierung, die Kernfelder und die Deduplizierungsregeln ab, die von allen Videoereignissen verwendet werden.                   |
| Ausgelieferte Anzeigen liefern eine realisierte `adId` (`citrusAdId`)                                                           | Stellt sicher, dass jede Videointeraktion der ausgelieferten Anzeige zugeordnet werden kann.                                                                   |
| Ein VAST 4.0-fähiger Player, der das `adm` -Tag rendert und `<TrackingEvents>`                                                  | Der Player löst die eingefügten Beacons bei tatsächlichem Wiedergabefortschritt aus.                                                                           |
| Der Player löst VAST-Makros auf (z. B. `[TIMESTAMP]`, `[CACHEBUSTING]`)                                                         | Ermöglicht es dem Player, jedes Beacon zum Zeitpunkt der Auslösung mit einem Zeitstempel zu versehen, anstatt dass Sie ihn ableiten müssen.                    |
| Sie lesen `UniversalAdId` `idValue` aus jedem `<Creative>`                                                                      | Dies ist die stabile ID pro Video, die Epsilon als `videoId` verwendet, um den Funnel zu verknüpfen (eine einzelne Anzeige kann mehr als ein Video enthalten). |
| Konsistente Tracking-ID pro Anzeigensitzung                                                                                     | Verwenden Sie `sessionId`, `customerId`, or `dtmToken` konsistent, damit das Reporting Ereignisse über die gesamte Sitzung hinweg zusammenführen kann.         |

## Was Epsilon heute ausliefert (und was Sie hinzufügen)

Das `adm` -Objekt in der Banner X -Antwort ist ein VAST 4.0-Tag. Epsilon bettet bereits das **Impression**- und **Click**-Tracking darin ein (`<Impression>` und `<VideoClicks><ClickTracking>`). Das Fortschritts- und Interaktions-Tracking wird **nicht** mitgeliefert — das ist das, was Sie einfügen.

Der Interaktions-Endpunkt akzeptiert bereits jeden unten stehenden Videotyp. Sie verbinden die beiden, indem Sie einen `<TrackingEvents>` -Block hinzufügen, dessen URLs `GET /v1/events/ad/interaction` -Beacons sind. Wenn der Player jeden Meilenstein überschreitet, löst er die passende URL aus. Lassen Sie die von Epsilonbereitgestellten `<Impression>` und `<ClickTracking>` -Knoten genau so, wie sie sind — Sie **fügen nur hinzu** `<TrackingEvents>`.

## Interaktionstypen für das Video-Reporting

Senden Sie bei jedem Videoereignis die Kernfelder plus `videoId` . `iabConsentString` ist das optionale Feld für alle Typen (URL-codiert). Lösen Sie Funnel-Ereignisse der Reihe nach aus, wenn der Player jeden Meilenstein erreicht, und verwenden Sie dieselbe `adId`, `videoId`und Tracking-ID für die gesamte Wiedergabesitzung.

### Funnel-Ereignisse

| `interactionType`    | Wann auszulösen                                                       | Reporting-Zweck                                                                          |
| -------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `videoCreativeView`  | Erster Video-Frame gerendert                                          | Basislinie für Video-Impressions                                                         |
| `videoPlay`          | Wiedergabe startet (benutzerinitiiert oder Autoplay gemäß Richtlinie) | Video-Startrate                                                                          |
| `videoFirstQuartile` | 25 % der Dauer angesehen                                              | Video-Funnel Q1                                                                          |
| `videoMidpoint`      | 50 % angesehen                                                        | Video-Funnel Q2                                                                          |
| `videoThirdQuartile` | 75 % angesehen                                                        | Video-Funnel Q3                                                                          |
| `videoComplete`      | 100 % angesehen                                                       | Fertigstellungsrate — Effektivität des Werbemittels und Rechtfertigung der Videoausgaben |

### Steuerungsereignisse

| `interactionType` | Wann auszulösen                  | Reporting-Zweck                            |
| ----------------- | -------------------------------- | ------------------------------------------ |
| `videoSkip`       | Nutzer überspringt vor Abschluss | Skip-Rate — Abbruch / Werbemittel-Probleme |
| `videoPause`      | Nutzer pausiert                  | Interaktionstiefe / Ablenkung              |
| `videoResume`     | Nutzer setzt nach Pause fort     | Erneute Interaktion nach Pause             |
| `videoMute`       | Nutzer schaltet Ton stumm        | Präferenz für Audio-Interaktion            |
| `videoUnmute`     | Nutzer aktiviert Ton wieder      | Aktives Audio-Interesse                    |

## VAST-Ereignisse zuordnen zu Epsilon Interaktionstypen

VAST-Player lösen Standard- `<Tracking event="…">` Callbacks aus. Fügen Sie unten einen `<Tracking>` Knoten pro Zeile ein, der auf den Interaktions-Endpunkt verweist, dem die `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`             |

Andere VAST-Ereignisse, die oben nicht genannt wurden (z. B. `progress`, `fullscreen`, `exitFullscreen`, `rewind`, `close`), sind nicht Teil des Epsilon Video-Reportings — fügen Sie dafür keine Beacons ein.

## Tracking-URL erstellen

Jede eingefügte `<Tracking>` URL ist ein einzelnes, URL-codiertes `GET` Beacon. Befüllen Sie es zur Erstellungszeit mit Werten aus der Anzeigenantwort und verwenden Sie ein VAST-Makro für den Zeitstempel, damit der Player ihn beim Auslösen stempelt.

```
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` — gelesen `citrusAdId` aus dem ausgelieferten Banner.
* `videoId` — gelesen `idValue` aus der `<UniversalAdId>` des Werbemittels, das Sie anbinden. Dies gilt pro Werbemittel: Wenn eine Anzeige mehrere Videos enthält, erhält jedes `<Creative>` seinen eigenen `<TrackingEvents>` Block unter Verwendung der `idValue`**dieses** Werbemittels, sodass der Funnel mit dem tatsächlich angesehenen Video verknüpft ist.
* `sessionId` — fügen Sie Ihre `sessionId` (or `customerId` / `dtmToken`) zur Erstellungszeit ein; der Endpunkt weist Ereignisse ohne Tracking-ID ab.
* `timestamp` — Verwenden Sie das `[TIMESTAMP]` VAST-Makro, damit der Player die echte ISO 8601-Auslösezeit einsetzt. Wenn Ihr Player dies nicht unterstützt, versehen Sie den Beacon auf andere Weise mit einem Zeitstempel, aber legen Sie nicht eine einzelne Zeit für alle Ereignisse fest.
* Hinzufügen `[CACHEBUSTING]` als Einweg-Parameter, wenn Ihr Player identische URLs zwischenspeichert.

## Einfügen `<TrackingEvents>` in das bereitgestellte VAST-Tag

Fügen Sie einen `<TrackingEvents>` -Block innerhalb jedes `<Creative>`'s `<Linear>` -Elements hinzu (nach `<VideoClicks>`, entsprechend dem VAST 4.0-Beispiel). Unten sind die `<Impression>` und `<ClickTracking>` sind Epsilon-bereitgestellt und bleiben unverändert; der hervorgehobene `<TrackingEvents>` -Block ist das, was Sie hinzufügen. Beachten Sie, `videoId` verwendet dieses Werbemittels wieder `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" %}
**Mehrere Videos in einer Anzeige** Wiederholen Sie den `<TrackingEvents>` -Block für jeden `<Creative>`, wobei jeder sein eigenes `UniversalAdId` `idValue` as `videoId`verwendet. **Teilen Sie niemals ein `idValue`** über Werbemittel hinweg — das ermöglicht es Epsilon den Funnel dem spezifischen bereitgestellten Video zuzuordnen.\*\*
{% endhint %}

## Wiedergabesequenz

Funnel-Ereignisse folgen dieser Reihenfolge über eine vollständige Wiedergabe:

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

| Regel                | Hinweise                                                                                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Funnel-Meilensteine  | Müssen an den tatsächlichen Wiedergabefortschritt gebunden sein. VAST-Player lösen Quartile bei echtem Fortschritt aus; synthetisieren Sie diese nicht beim Suchen. |
| Steuerungsereignisse | `videoSkip`, `videoPause`, `videoResume`, `videoMute`, und `videoUnmute` können zu jedem Zeitpunkt während der Wiedergabe ausgelöst werden.                         |
| Sitzungszuordnung    | Verwenden Sie dieselbe `adId`, `videoId` (`idValue`), und Tracking-ID über die gesamte Sitzung hinweg wieder, damit der Funnel zusammenhängt.                       |

## Alternative — Zählpixel über Player-Callbacks auslösen

Wenn Ihr Player kein VAST ausgeben kann `<TrackingEvents>`, oder das Video nicht über VAST bereitgestellt wird, lösen Sie dieselben Zählpixel direkt über Player-Callbacks aus. Endpunkt und Felder sind identisch — Sie erstellen die URL lediglich im Code statt im VAST-Tag.

### Schritt 1 — Kontext erfassen

Lesen Sie `adId` (`citrusAdId`) und die des Werbemittels `UniversalAdId` `idValue` zur Verwendung als `videoId`. Verwenden Sie die Sitzungs-Tracking-ID erneut.

### Schritt 2 — Funnel-Meilensteine über Player-Callbacks auslösen

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

### Schritt 3 — Steuerungsereignisse beim Auftreten auslösen

Hängen Sie sich an Überspringen/Pause/Fortsetzen/Stummschalten/Ton einschalten an und lösen Sie den passenden Typ aus. Entprellen Sie schnelle Umschaltungen.

## Beispielanfragen

Die eingefügten VAST-URLs und die manuellen Zählpixel führen zur selben `GET` -Anfrage. Die vollständigen URLs unten sind zur besseren Lesbarkeit umgebrochen — senden Sie diese als einzelnen codierten Query-String.

### Wiedergabe des Videos

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

### Quartil-Meilenstein

Gleiche Struktur für `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
```

### Steuerungsereignis

Gleiche Struktur für `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
```

## Wie ein gutes Ergebnis aussieht

| Bereich              | Erwartetes Ergebnis                                                                                                                          |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Eingefügtes Tracking | Jedes `<Creative>` enthält einen `<TrackingEvents>` -Block; jede `<Tracking>` -URL verwendet die dieses Werbemittels `idValue` as `videoId`. |
| Quartil-Ereignisse   | Quartile treffen in der richtigen Reihenfolge ein, mit genau einem `videoComplete` für ein vollständiges Ansehen.                            |
| Steuerungsereignisse | Ereignisse duplizieren sich nicht über die Entduplizierungsregeln hinaus.                                                                    |
| Erneutes Ansehen     | Erneutes Ansehen in derselben Sitzung verwendet `videoId` erneut und bleibt zuordenbar.                                                      |

## Fehlerbehebung (Video-Spezifika)

| Problem                                                                  | Wahrscheinliche Ursache                                                               | Maßnahme                                                                                                                                        |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Keine Fortschrittsereignisse treffen ein, nur Impression/Klick           | `<TrackingEvents>` nicht eingefügt oder außerhalb von `<Linear>`.                     | Fügen Sie den Block innerhalb jedes `<Creative>`'s `<Linear>` ein und bestätigen Sie, dass der Player ihn parst.                                |
| Alle Ereignisse teilen sich einen Zeitstempel                            | `[TIMESTAMP]` -Makro wurde vom Player nicht erweitert.                                | Bestätigen Sie die Makro-Unterstützung oder stempeln Sie pro Auslösung; codieren Sie nicht eine einzelne Zeit fest.                             |
| Ereignisse kommen an, können aber keinem Video zugeordnet werden         | `videoId` fehlt oder wird werbemittelübergreifend wiederverwendet.                    | Setzen Sie `videoId` auf die jeweilige eigene des Werbemittels `UniversalAdId` `idValue`.                                                       |
| Ereignisse geben HTTP 400 zurück                                         | Uncodierte URL, fehlende Tracking-ID oder unbekannter `interactionType`.              | Codieren Sie die gesamte `<Tracking>` -URL als URL; fügen Sie `sessionId`/`customerId`/`dtmToken`ein; verwenden Sie exakt den zugewiesenen Typ. |
| Ereignisse erscheinen in festen Intervallen statt passend zur Wiedergabe | Zählpixel wurden über einen Timer statt über den tatsächlichen Fortschritt ausgelöst. | Binden Sie jedes Ereignis an die tatsächlichen Fortschritts-Callbacks des Players (VAST erledigt dies für Sie).                                 |
| `videoComplete` wird mehr als einmal ausgelöst                           | Completion-Handler wird auch bei Schleife oder Wiederholung ausgelöst.                | Entprellen und beschränken Sie auf eine einzelne Fertigstellung pro Wiedergabe.                                                                 |
| `videoComplete` wird beim Laden ausgelöst                                | Das Completion-Ereignis ist an das Laden statt an 100 % Wiedergabe gebunden.          | Binden Sie `videoComplete` an das tatsächliche Ende der Wiedergabe.                                                                             |

Für die allgemeine Fehlerbehebung von Endpunkten siehe den [Technische Referenz](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) -Abschnitt zur Fehlerbehebung.

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