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

# Melden von Anzeigen-Interaktions-Ereignissen

Die Berichterstattung über Anzeigen-Interaktionsereignisse bietet eine zusätzliche Berichterstattungsebene für Kampagnen, mit der Sie und Ihre Marken verstehen können, wie Kunden mit Ihren Anzeigen interagieren.

Shoppable Banner X und Video Banner X -Integrationen senden Ereignisse an denselben Endpunkt mit demselben Transport, derselben Authentifizierung und denselben Kernfeldern. Lesen Sie dies einmal durch und folgen Sie dann der Anleitung für den Bericht, den Sie aktivieren möchten.

## Wie die Integrationen zusammenpassen

Der Interaktions-Endpunkt treibt drei Berichterstattungsergebnisse an. Diese Seite ist die gemeinsame Referenz; jedes Ergebnis hat seine eigene Aufgabenanleitung, die für die technischen Details hierher zurückverlinkt.

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

| Ergebnis         | Endpunkt       | Interaktionstypen (Zusammenfassung)                                 |
| ---------------- | -------------- | ------------------------------------------------------------------- |
| Shoppable Banner | ad/interaction | productImpression, productClick, creativeClick, cart                |
| Video            | ad/interaction | videoWerbemittelView, videoPlay, quartiles, videoComplete, controls |

## Bevor Sie beginnen (Gemeinsame Voraussetzungen)

| Voraussetzung                                                                        | Zweck                                                                                                           |
| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| Händler-Namespace / Katalog bereitgestellt und Integrations-Basis-URL ausgegeben     | Bestätigt, dass die Händlerumgebung bereit ist, Interaktionsereignisse zu empfangen.                            |
| Ausgelieferte Anzeigen geben eine realisierte adId                                   | Ermöglicht die Zuordnung jedes Ereignisses zur ausgelieferten Anzeige.                                          |
| Katalog-IDs (productCode, catalogId) im Anzeigenkontext verfügbar; videoId für Video | Stellt den Produkt- oder Videokontext bereit, der vom entsprechenden Berichterstattungsleitfaden benötigt wird. |
| Konsistente Tracking-IDs (sessionId, customerId, oder dtmToken) pro Anzeigensitzung  | Ermöglicht Attributierung und Deduplizierung über Ereignisse in derselben Sitzung hinweg.                       |
| Aktivierung der Berichterstattung für das Konto bestätigt                            | Stellt sicher, dass akzeptierte Ereignisse in die Berichterstattungsergebnisse einfließen können.               |

### Endpunkt & Transport

* Methode:\*\* HTTPS `GET` mit Abfrageparametern; kein Anfrage-Body.
* Endpunkt: `GET https://integration.{retailer}.citrusad.com/v1/events/ad/interaction`
* Antwort: `HTTP 200` bei Akzeptanz, `HTTP 400` bei Validierungsfehlern, `5xx` bei Plattformfehlern.

### Authentifizierung & Sicherheit

* Fire-and-forget:\*\* Verwenden Sie `navigator.sendBeacon`, ein 1×1-Bild oder `fetch(…, { keepalive: true })` , damit Ereignisse das Entladen der Seite überstehen.
* **Wiederholen Sie einen HTTP 400 nicht** — er ist fehlerhaft und wird erneut fehlschlagen. Korrigieren Sie stattdessen die Anfrage.
* **URL-codieren Sie alle Werte**, insbesondere den Consent-String und alle URL-Felder.

### Kernfelder (Jedes Ereignis)

| Feld                                    | Typ    | Erforderlich          | Beschreibung                                                                                                               | Akzeptierte Werte                           |
| --------------------------------------- | ------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `adId`                                  | string | Ja                    | Realisierte Anzeigen-ID der ausgelieferten Anzeige                                                                         | —                                           |
| `interactionType`                       | string | Ja                    | Ereignistyp (camelCase mit Groß-/Kleinschreibung)                                                                          | Siehe die leitfadenspezifischen Anleitungen |
| `timestamp`                             | string | Ja                    | Ereigniszeit (ISO 8601; UTC oder lokale Händlerzeit konsistent verwenden)                                                  | ISO 8601                                    |
| `sessionId` / `customerId` / `dtmToken` | string | Ja (mindestens eines) | Tracking-ID — mindestens eine erforderlich; wenn alle fehlen, kann das Ereignis nicht zugewiesen werden und wird abgelehnt | —                                           |

Verwenden Sie eine Tracking-ID für die gesamte Anzeigensitzung wieder und verwenden Sie dieselbe `adId` für jedes Ereignis dieser ausgelieferten Anzeige wieder. Jede `interactionType` wird einer spezifischen Berichterstellungsmetrik zugeordnet — siehe die anleitungsspezifische Anleitung für den "Berichterstellungszweck" jedes Typs.

### Bezeichner

Die IDs, die Ereignisse mit Anzeigen, Produkten und Sitzungen verknüpfen. Ereignisspezifische Feldanforderungen finden Sie in den jeweiligen Anleitungen; dies ist die gemeinsame Definition davon, woher jede ID stammt.

| Bezeichner                              | Was es ist                               | Woher es kommt                     | Verwendet von                     |
| --------------------------------------- | ---------------------------------------- | ---------------------------------- | --------------------------------- |
| `adId`                                  | Realisierte Anzeigen-ID                  | Die ausgelieferte Anzeigen-Antwort | Jedes Ereignis                    |
| `productCode` / `catalogId`             | SKU + deren Katalogbereich               | Händlerkatalog / Anzeigenkontext   | Produkt- und Warenkorb-Ereignisse |
| `videoId`                               | Stabile Video-Asset-ID                   | Das Video-Werbemittel              | Video-Ereignisse                  |
| `creativeId`                            | ID des Nicht-Produkt-Werbemittelelements | Das Werbemittel                    | `creativeClick`                   |
| `sessionId` / `customerId` / `dtmToken` | Tracking-ID (beliebige)                  | Händlersitzung / Login / DTM       | Jedes Ereignis                    |

### Implementierungsmuster (Beacon)

Verwenden Sie ein 1×1-Bild, `fetch` mit `keepalive`, or `navigator.sendBeacon` das auf die vollständige GET-URL verweist. Verlassen Sie sich bei der UX nicht auf das Parsen des Antwortkörpers. Dasselbe Helper-Tool dient allen drei Integrationen — die anpassungsbezogenen Leitfäden unterscheiden sich nur darin, welche `interactionType` und Felder Sie übergeben.

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