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

# Integrera interaktionsrapportering för Banner X Video

## Vad detta aktiverar

Videorapportering visar hur långt shoppare tittar – visning av annonskreativ, uppspelning, framsteg per kvartil och slutförande – samt kontrollåtgärder (hoppa över, pausa, stäng av ljudet). Det fungerar för Banner X videoannonskreativ.

Banner X video återges vanligtvis via en VAST 4.0-spelare som du också har integrerad, så det snabbaste sättet att aktivera denna rapportering är att låta spelaren utlösa händelserna åt dig: Epsilon returnerar en VAST-tagg i `adm` -fältet i annonssvaret, och du infogar ett `<TrackingEvents>` -block som pekar varje delmål för uppspelning mot interaktionsslutpunkten. Den här guiden visar hur du bygger det blocket. Om din spelare inte kan sända VAST-spårning (eller om videon inte levereras via VAST), använd [manuell beacon-reserv](#alternative--fire-beacons-from-player-callbacks) istället.

Den här guiden täcker endast typerna av videointeraktioner och hur du kopplar dem via VAST. För slutpunkt, autentisering, kärnfält, beacon-mekanik, avdubblering och testning, se [**Teknisk referens**](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference).

## Förutsättningar

| Förutsättning                                                                                                      | Varför det är viktigt                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Läs [Teknisk referens](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) | Täcker slutpunkt, autentisering, kärnfält och avdubbleringsregler som används av alla videohändelser.                                                |
| Levererade annonser returnerar en realiserad `adId` (`citrusAdId`)                                                 | Säkerställer att varje videointeraktion kan tillskrivas den levererade annonsen.                                                                     |
| En VAST 4.0-kompatibel spelare som återger `adm` -taggen och utlöser `<TrackingEvents>`                            | Spelaren utlöser de infogade beacons vid faktisk uppspelningsframgång.                                                                               |
| Spelaren utökar VAST-makron (t.ex. `[TIMESTAMP]`, `[CACHEBUSTING]`)                                                | Låter spelaren stämpla varje beacon vid tidpunkten för utlösning istället för att du härleder det.                                                   |
| Du läser `UniversalAdId` `idValue` från varje `<Creative>`                                                         | Detta är det stabila id:t per video som Epsilon använder som `videoId` för att knyta ihop tratten (en enskild annons kan innehålla mer än en video). |
| Konsekvent spårnings-id per annonssession                                                                          | Använd `sessionId`, `customerId`, or `dtmToken` konsekvent så att rapporteringen kan slå ihop händelser över sessionen.                              |

## Vad Epsilon visas idag (och vad du lägger till)

Det `adm` -objektet i Banner X -svaret är en VAST 4.0-tagg. Epsilon kopplar redan **impression**- och **click**-spårning till den (`<Impression>` och `<VideoClicks><ClickTracking>`). Den levererar **inte** framstegs- och interaktionsspårning – det är vad du infogar.

Interaktionsslutpunkten accepterar redan alla videotyper nedan. Du överbryggar de två genom att lägga till ett `<TrackingEvents>` -block vars URL:er är `GET /v1/events/ad/interaction` -beacons. När spelaren passerar varje delmål utlöser den matchande URL. Lämna de Epsilon-levererade `<Impression>` och `<ClickTracking>` -noderna exakt som de är – du **lägger bara till** `<TrackingEvents>`.

## Interaktionstyper för videorapportering

Skicka kärnfälten plus `videoId` vid varje videohändelse. `iabConsentString` är det valfria fältet på alla typer (URL-kodat). Utlös tratthändelser i ordning när spelaren når varje delmål, och återanvänd samma `adId`, `videoId`, och spårnings-id för hela visningssessionen.

### Tratthändelser

| `interactionType`    | När den ska utlösas                                                                  | Rapporteringssyfte                                                                |
| -------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| `videoCreativeView`  | Första videoramen återgiven                                                          | Baslinje för videovisning                                                         |
| `videoPlay`          | Uppspelningen startar (användarinitierad eller automatisk uppspelning enligt policy) | Videostartfrekvens                                                                |
| `videoFirstQuartile` | 25 % av varaktigheten tittad                                                         | Videotrattskvartil 1                                                              |
| `videoMidpoint`      | 50 % tittat                                                                          | Videotrattskvartil 2                                                              |
| `videoThirdQuartile` | 75 % tittat                                                                          | Videotrattskvartil 3                                                              |
| `videoComplete`      | 100 % tittat                                                                         | Fullföljandegrad — annonskreativets effektivitet och motivering av videokostnader |

### Kontrollhändelser

| `interactionType` | När den ska utlösas                          | Rapporteringssyfte                                  |
| ----------------- | -------------------------------------------- | --------------------------------------------------- |
| `videoSkip`       | Användaren hoppar över innan det är slutfört | Skeppningsgrad — avhopp / problem med annonskreativ |
| `videoPause`      | Användaren pausar                            | Engagemangsdjup / distraktion                       |
| `videoResume`     | Användaren återupptar efter paus             | Återengagemang efter paus                           |
| `videoMute`       | Användaren stänger av ljudet                 | Ljudengagemangspreferens                            |
| `videoUnmute`     | Användaren slår på ljudet                    | Aktivt ljudintresse                                 |

## Koppla VAST-händelser till Epsilon interaktionstyper

VAST-spelare utlöser standardmässiga `<Tracking event="…">` återanrop. Infoga en `<Tracking>` nod per rad nedan, som pekar på interaktionsslutpunkten med den kopplade `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`             |

Andra VAST-händelser som inte nämns ovan (t.ex. `progress`, `fullscreen`, `exitFullscreen`, `rewind`, `close`) ingår inte i Epsilon videorapportering — infoga inte beacons för dem.

## Konstruera spårnings-URL:en

Varje infogad `<Tracking>` URL är en enskild, URL-kodad `GET` beacon. Fyll den vid byggtillfället med värden från annonssvaret, och använd ett VAST-makro för tidsstämpeln så att spelaren stämplar den när den utlöses.

```
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` — läs `citrusAdId` från den levererade bannern.
* `videoId` — läs `idValue` från `<UniversalAdId>` på det annonskreativ du kopplar. Detta är per annonskreativ: om en annons innehåller flera videor får varje `<Creative>` sitt eget `<TrackingEvents>` block som använder **det** annonskreativets `idValue`, så att tratten kopplas tillbaka till videon som faktiskt tittades på.
* `sessionId` — infoga din `sessionId` (or `customerId` / `dtmToken`) vid byggtillfället; slutpunkten avvisar händelser utan spårnings-id.
* `timestamp` — använd `[TIMESTAMP]` VAST-makro så att spelaren ersätter det med den faktiska ISO 8601-utlösningstiden. Om din spelare inte stödjer det, stämpla beaconen på ett annat sätt, men hårdkoda inte en enskild tid för alla händelser.
* Lägg till `[CACHEBUSTING]` som en engångsparameter om din spelare cachar identiska URL:er.

## Infoga `<TrackingEvents>` i den levererade VAST-taggen

Lägg till ett `<TrackingEvents>` block inuti varje `<Creative>`'s `<Linear>` element (efter `<VideoClicks>`, vilket matchar VAST 4.0-exemplet). Nedan är `<Impression>` och `<ClickTracking>` är Epsilonlevererade och lämnas orörda; det markerade `<TrackingEvents>` blocket är vad du lägger till. Observera `videoId` återanvänder detta annonskreativs `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" %}
**Flera videor i en annons** Upprepa `<TrackingEvents>` blocket för varje `<Creative>`, som var och en använder sin egen `UniversalAdId` `idValue` as `videoId`. **Dela aldrig en `idValue`** mellan annonskreativ — det är vad som gör att\*\* Epsilon kan tillskriva tratten till den specifika video som levererades.\*\*
{% endhint %}

## Uppspelningssekvens

Tratthändelser följer denna ordning under en hel visning:

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

| Regel                | Vägledning                                                                                                                                      |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Milstolpar i tratten | Måste vara kopplade till faktiska uppspelningsframsteg. VAST-spelare utlöser kvartiler vid verkliga framsteg; syntetisera dem inte vid sökning. |
| Kontrollhändelser    | `videoSkip`, `videoPause`, `videoResume`, `videoMute`, och `videoUnmute` kan utlösas när som helst under uppspelningen.                         |
| Sessionsattribuering | Återanvänd samma `adId`, `videoId` (`idValue`), och spårnings-id över sessionen så att trattarna kopplas ihop.                                  |

## Alternativ — utlös beacons från spelarens återanrop

Om din spelare inte kan sända VAST `<TrackingEvents>`, eller om videon inte levereras via VAST, utlös samma beacons direkt från spelarens återanrop. Slutpunkten och fälten är identiska — du konstruerar bara URL:en i kod istället för i VAST-taggen.

### Steg 1 — Fånga kontext

Läs `adId` (`citrusAdId`) och annonskreativets `UniversalAdId` `idValue` att använda som `videoId`. Återanvänd sessionens spårnings-id.

### Steg 2 — Utlös trattmilstolpar från spelarens återanrop

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

### Steg 3 — Utlös kontrollhändelser när de inträffar

Koppla skip/pause/resume/mute/unmute och utlös motsvarande typ. Avstudsa (debounce) snabba växlingar.

## Exempelförfrågningar

De injicerade VAST-URL:erna och de manuella beaconsen motsvarar samma `GET` begäran. Fullständiga URL:er nedan är radbrutna för läsbarhet — skicka som en enda kodad söksträng.

### Videouppspelning

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

### Kvartilsmilstolpe

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

### Kontrollhändelse

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

## Hur bra ser ut

| Område             | Förväntat resultat                                                                                                                  |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| Injicerad spårning | Varje `<Creative>` bär en `<TrackingEvents>` blockera; varje `<Tracking>` URL använder det annonskreativets `idValue` as `videoId`. |
| Kvartilshändelser  | Kvartiler anländer i ordning, med exakt en `videoComplete` för en hel visning.                                                      |
| Kontrollhändelser  | Händelser dupliceras inte utöver avdupliceringsreglerna.                                                                            |
| Omvisningar        | Omvisningar i samma session återanvänder `videoId` och förblir tillskrivningsbara.                                                  |

## Felsökning (videospecifikt)

| Problem                                                                     | Trolig orsak                                                                 | Åtgärd                                                                                                          |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Inga framstegshändelser anländer, endast impression/click                   | `<TrackingEvents>` inte injicerad, eller tillagd utanför `<Linear>`.         | Lägg till blocket inuti varje `<Creative>`'s `<Linear>` och bekräfta att spelaren tolkar det.                   |
| Alla händelser delar en tidsstämpel                                         | `[TIMESTAMP]` makrot expanderas inte av spelaren.                            | Bekräfta makrostöd, eller tidsstämpla per utlösning; hårdkoda inte en tid.                                      |
| Händelser landar men kan inte tillskrivas en video                          | `videoId` saknas eller återanvänds över annonskreativ.                       | Ställ in `videoId` till varje annonskreativs eget `UniversalAdId` `idValue`.                                    |
| Händelser returnerar HTTP 400                                               | Okodad URL, saknat spårnings-id eller okänd `interactionType`.               | URL-koda hela `<Tracking>` URL; inkludera `sessionId`/`customerId`/`dtmToken`; använd den exakta mappade typen. |
| Händelser visas vid fasta intervaller istället för att matcha uppspelningen | Beacons utlöses på en timer istället för faktiska framsteg.                  | Koppla varje händelse till spelarens faktiska framstegsåteranrop (VAST gör detta åt dig).                       |
| `videoComplete` utlöses mer än en gång                                      | Slutförandehanteraren utlöses också vid loop eller återuppspelning.          | Avstudsa (debounce) och begränsa till ett enda slutförande per uppspelning.                                     |
| `videoComplete` utlöses vid inläsning                                       | Slutförandehändelsen är kopplad till inläsning snarare än 100 % uppspelning. | Koppla `videoComplete` till faktiskt slut på uppspelningen.                                                     |

För allmän felsökning av slutpunkter, se [Teknisk referens](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) felsökningsavsnittet.

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