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

# Hlásenie udalostí interakcie s reklamou

Reportovanie udalostí interakcie s reklamou poskytuje dodatočnú vrstvu reportovania pre kampane, ktorá vám a vašim značkám umožňuje pochopiť, ako zákazníci interagujú s vašimi reklamami.

Nákupné Banner X a video Banner X integrácie odosielajú udalosti na rovnaký koncový bod s rovnakým prenosom, autentifikáciou a základnými poľami. Prečítajte si to raz a potom postupujte podľa sprievodcu pre report, ktorý chcete povoliť.

## Ako integrácie do seba zapadajú

Koncový bod pre interakcie poháňa tri výsledky reportovania. Táto stránka slúži ako spoločný prehľad; každý výsledok má vlastného sprievodcu úlohami, ktorý odkazuje späť sem na technické prepojenie.

```
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ýsledok       | Koncový bod    | Typy interakcií (zhrnutie)                                                      |
| -------------- | -------------- | ------------------------------------------------------------------------------- |
| Nákupný banner | ad/interaction | productImpression, productClick, creativeClick, cart                            |
| Video          | ad/interaction | videoReklamný materiálView, videoPlay, kvartily, videoComplete, ovládacie prvky |

## Skôr než začnete (Spoločné predpoklady)

| Predpoklad                                                                           | Účel                                                                                     |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| Menný priestor predajcu / katalóg vytvorený a základná URL adresa integrácie vydaná  | Potvrdzuje, že prostredie predajcu je pripravené na prijímanie udalostí interakcie.      |
| Zobrazené reklamy vracajú realizované adId                                           | Umožňuje pripojiť každú udalosť k zobrazenej reklame.                                    |
| ID katalógov (productCode, catalogId) dostupné v kontexte reklamy; videoId pre video | Poskytuje kontext produktu alebo videa potrebný pre príslušného sprievodcu reportovaním. |
| Konzistentné sledovacie ID (sessionId, customerIdalebo dtmToken) na reláciu reklamy  | Umožňuje atribuciu a deduplikáciu naprieč udalosťami v rovnakej relácii.                 |
| Povolenie reportovania potvrdené pre účet                                            | Zabezpečuje, že prijaté udalosti môžu prúdiť do výstupov reportovania.                   |

### Koncový bod a prenos

* Metóda:\*\* HTTPS `GET` s parametrami dopytu; bez tela požiadavky.
* Koncový bod: `GET https://integration.{retailer}.citrusad.com/v1/events/ad/interaction`
* Odpoveď: `HTTP 200` pri prijatí, `HTTP 400` pri zlyhaní validácie, `5xx` pri chybe platformy.

### Autentifikácia a bezpečnosť

* Odoslať a zabudnúť (fire-and-forget):\*\* použite `navigator.sendBeacon`, obrázok 1×1, alebo `fetch(…, { keepalive: true })` aby udalosti prežili opustenie stránky.
* **Neopakujte požiadavku HTTP 400** — je chybne formátovaná a zlyhá znova. Namiesto toho opravte požiadavku.
* **Všetky hodnoty zakódujte do URL**, najmä reťazec súhlasu a akékoľvek polia URL.

### Základné polia (každá udalosť)

| Pole                                    | Typ     | Povinné           | Popis                                                                                                    | Akceptované hodnoty                            |
| --------------------------------------- | ------- | ----------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `adId`                                  | reťazec | Áno               | Realizované ID reklamy zo zobrazenej reklamy                                                             | —                                              |
| `interactionType`                       | reťazec | Áno               | Typ udalosti (camelCase s rozlišovaním malých a veľkých písmen)                                          | Pozrite si sprievodcov pre jednotlivé výsledky |
| `timestamp`                             | reťazec | Áno               | Čas udalosti (ISO 8601; používajte konzistentne UTC alebo miestny čas predajcu)                          | ISO 8601                                       |
| `sessionId` / `customerId` / `dtmToken` | reťazec | Áno (aspoň jeden) | Sledovacie ID — vyžaduje sa aspoň jedno; ak chýbajú všetky, udalosť nemožno atribuovať a bude odmietnutá | —                                              |

Znova použite jedno sledovacie ID pre celú reláciu reklamy a použite rovnaké `adId` naprieč každou udalosťou pre danú zobrazenú reklamu. Každé `interactionType` sa mapuje na špecifickú metriku reportovania — pozrite si sprievodcu pre jednotlivé výsledky pre "účel reportovania" každého typu.

### Identifikátory

ID, ktoré spájajú udalosti s reklamami, produktmi a reláciami. Požiadavky na polia pre jednotlivé udalosti sa nachádzajú v každom sprievodcovi; toto je spoločná definícia toho, odkiaľ každé ID pochádza.

| Identifikátor                           | Čo to je                                     | Odkiaľ pochádza                      | Používané od               |
| --------------------------------------- | -------------------------------------------- | ------------------------------------ | -------------------------- |
| `adId`                                  | Realizované id reklamy                       | Doručená odpoveď reklamy             | Každá udalosť              |
| `productCode` / `catalogId`             | SKU + jeho katalógový rozsah                 | Katalóg predajcu / kontext reklamy   | Udalosti produktu a košíka |
| `videoId`                               | Stabilné id video aktíva                     | Video reklamný materiál              | Udalosti videa             |
| `creativeId`                            | Id neproduktového prvku reklamného materiálu | Reklamný materiál                    | `creativeClick`            |
| `sessionId` / `customerId` / `dtmToken` | Sledovacie id (akékoľvek)                    | Relácia predajcu / prihlásenie / DTM | Každá udalosť              |

### Vzor implementácie (Beacon)

Použite obrázok 1×1, `fetch` s `keepalive`, or `navigator.sendBeacon` namiereným na úplnú adresu GET URL. Nespoliehajte sa na spracovanie tela odpovede pre UX. Ten istý pomocník slúži pre všetky tri integrácie — návody pre jednotlivé výsledky sa líšia len v tom, ktoré `interactionType` a polia odovzdávate.

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