> 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.md).

# Rapportering av annonsinteraktionshändelser

Rapportering om annonsinteraktionshändelser ger ett ytterligare rapporteringslager till kampanjer som gör att du och dina varumärken kan förstå hur kunder interagerar med dina annonser.

Shoppable Banner X och Video Banner X -integrationer skickar händelser till samma slutpunkt med samma transport, autentisering och kärnfält. Läs detta en gång och följ sedan guiden för den rapport du vill aktivera.

## Hur integrationerna hänger ihop

Slutpunkten för interaktioner driver tre rapporteringsresultat. Den här sidan är den gemensamma referensen; varje resultat har sin egen uppgiftsguide som länkar tillbaka hit för den tekniska strukturen.

```
Ad serving (returns a realised adId)
        │
        ▼
GET /v1/events/ad/interaction   ← this reference: transport, auth, core fields, dedup, errors
        │
        ├─ adInteraction .......... Shoppable Banner reporting
        └─ adInteraction .......... Video reporting
```

| Resultat         | Slutpunkt      | Interaktionstyper (sammanfattning)                                    |
| ---------------- | -------------- | --------------------------------------------------------------------- |
| Shoppable Banner | ad/interaction | productImpression, productClick, creativeClick, cart                  |
| Video            | ad/interaction | videoAnnonskreativView, videoPlay, quartiles, videoComplete, controls |

## Innan du börjar (gemensamma förutsättningar)

| Förutsättning                                                                             | Syfte                                                                                           |
| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Återförsäljarens namnområde / katalog tillhandahållen och integrationens bas-URL utfärdad | Bekräftar att återförsäljarens miljö är redo att ta emot interaktionshändelser.                 |
| Visade annonser returnerar en realiserad adId                                             | Gör det möjligt att koppla varje händelse till den visade annonsen.                             |
| Katalog-ID:n (productCode, catalogId) tillgängliga i annonskontexten; videoId för video   | Tillhandahåller den produkt- eller videokontext som behövs i den relevanta rapporteringsguiden. |
| Konsekvent spårnings-ID (sessionId, customerId, eller dtmToken) per annonssession         | Möjliggör attribuering och avduplicering över händelser i samma session.                        |
| Rapporteringsaktivering bekräftad för kontot                                              | Säkerställer att godkända händelser kan flöda vidare till rapporteringsutdata.                  |

### Slutpunkt & transport

* Metod:\*\* HTTPS `GET` med frågeparametrar; ingen anropstext.
* Slutpunkt: `GET https://integration.{retailer}.citrusad.com/v1/events/ad/interaction`
* Svar: `HTTP 200` vid godkännande, `HTTP 400` vid valideringsfel, `5xx` vid plattformsfel.

### Autentisering & säkerhet

* Fire-and-forget:\*\* använd `navigator.sendBeacon`, en 1×1-bild, eller `fetch(…, { keepalive: true })` så att händelser överlever att sidan lämnas.
* **Försök inte igen vid HTTP 400** — den är felaktigt utformad och kommer att misslyckas igen. Korrigera begäran istället.
* **URL-koda alla värden**, särskilt samtyckessträngen och eventuella URL-fält.

### Kärnfält (varje händelse)

| Fält                                    | Typ    | Obligatoriskt         | Beskrivning                                                                               | Godkända värden                     |
| --------------------------------------- | ------ | --------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------- |
| `adId`                                  | sträng | Ja                    | Realiserat annons-ID från den visade annonsen                                             | —                                   |
| `interactionType`                       | sträng | Ja                    | Händelsetyp (skiftlägeskänslig camelCase)                                                 | Se guiderna för respektive resultat |
| `timestamp`                             | sträng | Ja                    | Händelsetid (ISO 8601; använd UTC eller återförsäljarens lokala tid konsekvent)           | ISO 8601                            |
| `sessionId` / `customerId` / `dtmToken` | sträng | Ja (vilken som helst) | Spårnings-ID — minst ett krävs; om alla saknas kan händelsen inte attribueras och avvisas | —                                   |

Återanvänd ett spårnings-ID för hela annonssessionen och återanvänd samma `adId` över varje händelse för den visade annonsen. Varje `interactionType` mappar till ett specifikt rapporteringsmått — se guiden för respektive resultat för "rapporteringssyftet" med varje typ.

### Identifierare

De ID:n som knyter händelser till annonser, produkter och sessioner. Fältkrav per händelse finns i varje guide; detta är den gemensamma definitionen av var varje ID kommer ifrån.

| Identifierare                           | Vad det är                            | Varifrån det kommer                     | Används av                      |
| --------------------------------------- | ------------------------------------- | --------------------------------------- | ------------------------------- |
| `adId`                                  | Förverkligat annons-ID                | Det levererade annonssvaret             | Varje händelse                  |
| `productCode` / `catalogId`             | SKU + dess katalogomfång              | Återförsäljarkatalog / annonskontext    | Produkt- och varukorgshändelser |
| `videoId`                               | Stabilt video-asset-ID                | Video-annonskreativet                   | Videohändelser                  |
| `creativeId`                            | Icke-produkt-annonskreativselement-ID | Annonskreativet                         | `creativeClick`                 |
| `sessionId` / `customerId` / `dtmToken` | Spårnings-ID (vilket som helst)       | Återförsäljarsession / inloggning / DTM | Varje händelse                  |

### Implementeringsmönster (Beacon)

Använd en 1×1-bild, `fetch` med `keepalive`, or `navigator.sendBeacon` riktad mot den fullständiga GET-URL:en. Lita inte på att tolka responskroppen för UX. Samma hjälpare betjänar alla tre integrationer — guiderna per resultat skiljer sig bara åt i vilka `interactionType` och fält du skickar.

```javascript
function fireAdInteraction(params) {
  const qs = new URLSearchParams(params);
  const url = `https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?${qs}`;
  if (navigator.sendBeacon) {
    navigator.sendBeacon(url);
  } else {
    new Image().src = url; // fallback
  }
}

// Example: product click (see the Shoppable Banner guide for the full set)
fireAdInteraction({
  adId: "shotgun_0001",
  timestamp: new Date().toISOString(),
  sessionId: getSessionId(),
  productCode: "prod-00001-01",
  catalogId: "catlg-custom-DAA001",
  interactionType: "productClick",
});
```

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