> 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/cs/data-api/api-overview/ad-interaction-events-reporting.md).

# Hlášení událostí interakce s reklamou

Hlášení událostí interakce s reklamou poskytuje dodatečnou vrstvu hlášení pro kampaně, která vám a vašim značkám umožní pochopit, jak zákazníci interagují s vašimi reklamami.

Nakupovatelné Banner X a Video Banner X integrace odesílají události na stejný koncový bod se stejným přenosem, autentizací a základními poli. Přečtěte si to jednou a poté postupujte podle průvodce pro hlášení, které chcete povolit.

## Jak integrace dohromady fungují

Koncový bod pro interakce zajišťuje tři výstupy hlášení. Tato stránka slouží jako sdílená reference; každý výstup má svého vlastní průvodce úkoly, který odkazuje zpět na tuto stránku s technickými detaily.

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

| Výstup               | Koncový bod    | Typy interakcí (souhrn)                                                   |
| -------------------- | -------------- | ------------------------------------------------------------------------- |
| Nakupovatelný banner | ad/interaction | productImpression, productClick, creativeClick, cart                      |
| Video                | ad/interaction | videoReklamní materiálView, videoPlay, quartiles, videoComplete, controls |

## Než začnete (sdílené předpoklady)

| Předpoklad                                                                          | Účel                                                                              |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Jmenný prostor prodejce / katalog zřízen a vydána základní URL integrace            | Potvrzuje, že prostředí prodejce je připraveno k přijímání událostí interakce.    |
| Zobrazované reklamy vracejí realizované adId                                        | Umožňuje připojit každou událost k zobrazované reklamě.                           |
| ID katalogu (productCode, catalogId) dostupná v kontextu reklamy; videoId pro video | Poskytuje kontext produktu nebo videa potřebný pro příslušného průvodce hlášením. |
| Konzistentní sledovací ID (sessionId, customerIdnebo dtmToken) na relaci reklamy    | Umožňuje atribuci a deduplikaci napříč událostmi ve stejné relaci.                |
| Povolení hlášení potvrzeno pro účet                                                 | Zajišťuje, že přijaté události mohou proudit do výstupů hlášení.                  |

### Koncový bod a přenos

* Metoda:\*\* HTTPS `GET` s parametry dotazu; bez těla požadavku.
* Koncový bod: `GET https://integration.{retailer}.citrusad.com/v1/events/ad/interaction`
* Odpověď: `HTTP 200` při přijetí, `HTTP 400` při chybě validace, `5xx` při chybě platformy.

### Autentizace a zabezpečení

* Fire-and-forget:\*\* použijte `navigator.sendBeacon`, obrázek 1×1, nebo `fetch(…, { keepalive: true })` aby události přežily opuštění stránky.
* **Neopakujte požadavek při HTTP 400** — je chybbně zformátovaný a selže znovu. Namísto toho požadavek opravte.
* **Kódujte všechny hodnoty do URL**, zejména řetězec souhlasu a všechna pole URL.

### Základní pole (každá událost)

| Pole                                    | Typ    | Povinné             | Popis                                                                                                 | Akceptované hodnoty                 |
| --------------------------------------- | ------ | ------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `adId`                                  | string | Ano                 | Realizované ID reklamy ze zobrazované reklamy                                                         | —                                   |
| `interactionType`                       | string | Ano                 | Typ události (camelCase s rozlišováním malých a velkých písmen)                                       | Viz průvodce pro jednotlivé výstupy |
| `timestamp`                             | string | Ano                 | Čas události (ISO 8601; používejte konzistentně UTC nebo místní čas prodejce)                         | ISO 8601                            |
| `sessionId` / `customerId` / `dtmToken` | string | Ano (alespoň jedno) | Sledovací ID — vyžadováno alespoň jedno; pokud chybí všechna, událost nelze atribuovat a je odmítnuta | —                                   |

Opakovaně používejte jedno sledovací ID pro celou relaci reklamy a používejte stejné `adId` napříč všemi událostmi pro tuto zobrazovanou reklamu. Každý `interactionType` se mapuje na konkrétní metriku hlášení — účel hlášení pro jednotlivé typy naleznete v průvodci pro daný výstup.

### Identifikátory

Identifikátory, které propojují události s reklamami, produkty a relacemi. Požadavky na pole pro jednotlivé události jsou v každém průvodci; toto je sdílená definice toho, odkud jednotlivá ID pocházejí.

| Identifikátor                           | Co to je                                     | Odkud to pochází                   | Používáno uživatelem       |
| --------------------------------------- | -------------------------------------------- | ---------------------------------- | -------------------------- |
| `adId`                                  | ID realizované reklamy                       | Odpověď na doručenou reklamu       | Každá událost              |
| `productCode` / `catalogId`             | SKU + jeho katalogový rozsah                 | Katalog prodejce / kontext reklamy | Události produktu a košíku |
| `videoId`                               | Stabilní ID video podkladu                   | Video reklamní materiál            | Události videa             |
| `creativeId`                            | ID neproduktového prvku reklamního materiálu | Reklamní materiál                  | `creativeClick`            |
| `sessionId` / `customerId` / `dtmToken` | Sledovací ID (libovolné)                     | Relace prodejce / přihlášení / DTM | Každá událost              |

### Vzor implementace (Beacon)

Použijte obrázek 1×1, `fetch` s `keepalive`, or `navigator.sendBeacon` namířeným na úplnou adresu URL GET. Nespoléhejte se na parsování těla odpovědi pro UX. Stejný pomocník obsluhuje všechny tři integrace — průvodci pro jednotlivé výsledky se liší pouze v tom, které `interactionType` a pole předáváte.

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