> 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/integrate-banner-x-shoppable-banner-interaction-reporting.md).

# Integrovať hlásenie interakcií s nakupovateľným bannerom pre Banner X

Nakupovateľný banner je Banner X reklama s viacerými aktívnymi zónami sprievodných produktov v jednom umiestnení. Keď tieto udalosti prúdia, prehľad kampane rozdelí výkonnosť bannera na každý sprievodný produkt — zobrazenia, kliknutia a CTR (plus akcie košíka, ak sú integrované) — namiesto jediného súhrnu na úrovni bannera.

Táto príručka sa zaoberá iba typmi interakcií s nakupovateľným bannerom. Pre koncový bod, autentifikáciu, základné polia (`adId`, `timestamp`, ID sledovania), mechaniku beaconov, deduplikáciu a testovanie si pozrite [Technickú referenciu pre reportovanie udalostí interakcie s reklamou](https://help.citrusad.com/retail-media-interface/integration/sk/data-api/api-overview/ad-interaction-events-reporting).

## Predpoklady

| Predpoklad                                                                                                                                                  | Účel                                                                                  |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Prečítajte si [Technickú referenciu](https://help.citrusad.com/retail-media-interface/integration/sk/data-api/api-overview/ad-interaction-events-reporting) | Potvrdzuje požiadavky na koncový bod, autentifikáciu, základné polia a deduplikáciu.  |
| Sprievodné produkty nakonfigurované na Banner X reklamnom materiáli                                                                                         | Zabezpečuje, že interakcie na úrovni produktov možno priradiť k reklamnému materiálu. |
| Vydané reklamy vracajú realizované `adId`                                                                                                                   | Spája každú udalosť s doručenou inštanciou reklamy.                                   |
| `productCode` a `catalogId` dostupné pre každý sprievodný produkt                                                                                           | Identifikuje produkt a katalóg použité v reportovaní.                                 |
| Pravidlo zobraziteľnosti dohodnuté pre dlaždice produktov                                                                                                   | Definuje, kedy sa dlaždica produktu považuje za videnú pre `productImpression`.       |
| Konzistentné ID sledovania na reláciu reklamy                                                                                                               | Podporuje atribuciu a deduplikáciu pomocou `sessionId`, `customerId`, or `dtmToken`.  |

## Typy interakcií pre reportovanie nakupovateľného bannera

Toto sú `adInteraction` udalosti (žiadne `moduleId`). Odošlite základné polia plus kľúčové polia uvedené nižšie. `productImpression` a `productClick` sú dve udalosti, ktoré sprístupňujú kartu Produkty — spustite obe.

| `interactionType`   | Kľúčové polia                                                    | Kedy spustiť                                                                     | Účel reportovania                                                                       |
| ------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `productImpression` | `productCode`, `catalogId`                                       | Dlaždica produktu/SKU sa stane viditeľnou podľa vašich pravidiel zobraziteľnosti | Zobrazenia podľa produktov — plní stĺpec zobrazení (a riadky s nulovým počtom kliknutí) |
| `productClick`      | `productCode`, `catalogId`                                       | Nakupujúci klikne na dlaždicu produktu/SKU                                       | Kliknutia podľa produktov — generuje kliknutia a CTR                                    |
| `creativeClick`     | `creativeId`                                                     | Kliknutie na neproduktový prvok reklamného materiálu                             | Zapojenie do neproduktového reklamného materiálu                                        |
| `cart`              | `productCode`, `catalogId`, `units`, voliteľné `conversionValue` | Zmena košíka z kontextu reklamy                                                  | Úmysel pridať do košíka / hodnota produktu                                              |

## Pravidlá zobraziteľnosti pre `productImpression`

| Pravidlo                                          | Usmernenie                                                                                                                                            |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Definujte, kedy sa dlaždica považuje za videnú    | Dohodnite sa na pravidle zobraziteľnosti, ako je percento viditeľnosti plus čas na obrazovke, a aplikujte ho konzistentne naprieč webom a aplikáciou. |
| Spustite zobrazenia raz za výskyt zobraziteľnosti | Ošetrite kmitanie pri skrolovaní a opätovné vykresľovanie (debounce), aby sa jedno videnie nepočítalo viackrát.                                       |

## Košík: Odošlite absolútny aktuálny počet kusov

Spustite `cart` pri každej interakcii s košíkom — počiatočné pridanie, každé `+`, každé `−`, a odstránenie (späť na `0`) — s `units` nastaveným na absolútny aktuálny počet kusov, nie deltu. Opätovné odoslanie aktuálneho súčtu udržiava počty správne aj pri deduplikácii. Pridajte `conversionValue` , keď ho máte.

{% hint style="info" %}
**Príklad** — nakupujúci pridá produkt, dvakrát zvýši počet a potom ho odstráni:\*\* `cart {units: 1}` → `cart {units: 2}` → `cart {units: 3}` → `cart {units: 0}`
{% endhint %}

## Implementácia krok za krokom

### Krok 1 — Zachyťte kontext reklamy

Prečítajte si realizované `adId` z doručenej reklamy a `productCode`/`catalogId` pre každú sprievodnú dlaždicu. Vytvorte jedno ID sledovania pre reláciu a znova ho použite pri zobrazeniach a kliknutiach.

### Krok 2 — Spustite zobrazenia produktu

Keď dlaždica spĺňa vaše pravidlo zobraziteľnosti, spustite `productImpression` raz pre daný produkt.

```javascript
navigator.sendBeacon(
  "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" +
  new URLSearchParams({
    adId, interactionType: "productImpression", sessionId,
    timestamp: new Date().toISOString(), productCode, catalogId
  })
);
```

### Krok 3 — Odoslanie udalosti kliknutia na produkt

```javascript
navigator.sendBeacon(
  "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" +
  new URLSearchParams({
    adId, interactionType: "productClick", sessionId,
    timestamp: new Date().toISOString(), productCode, catalogId
  })
);
```

### Krok 4 — Odoslanie zmien v košíku

Pri pridaní/aktualizácii odošlite `cart` s absolútnym aktuálnym `units` pre daný produkt (a `conversionValue` ak ho máte) — pozrite si pravidlo pre košík vyššie.

## Vzorové požiadavky

Úplné URL adresy GET (zalomené pre prehľadnosť — odosielajte ako jeden kódovaný dopytovací reťazec).

### Zobrazenie produktu

```http
GET https://integration.retailer.citrusad.com/v1/events/ad/interaction
  ?adId=shotgun_0001
  &timestamp=2026-05-20T10:15:00Z
  &sessionId=12345gsyuhf-6678ghsj
  &productCode=prod-00001-01
  &catalogId=catlg-custom-DAA001
  &interactionType=productImpression
```

### Kliknutie na produkt

```http
GET https://integration.retailer.citrusad.com/v1/events/ad/interaction
  ?adId=shotgun_0001
  &timestamp=2026-05-20T10:15:30Z
  &sessionId=12345gsyuhf-6678ghsj
  &productCode=prod-00001-01
  &catalogId=catlg-custom-DAA001
  &interactionType=productClick
```

### Pridanie do košíka z reklamy

```http
GET https://integration.retailer.citrusad.com/v1/events/ad/interaction
  ?adId=shotgun_0001
  &timestamp=2026-05-20T10:16:00Z
  &customerId=cust-abc-123
  &productCode=prod-00001-01
  &catalogId=catlg-custom-DAA001
  &interactionType=cart
  &units=2
  &conversionValue=29.99
```

## Ako vypadá správny výsledok

| Kontrola                         | Detail                                                                                                                           |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Udalosti vracajú HTTP 200        | `productImpression` a `productClick` vracajú HTTP 200 v PRE/QA.                                                                  |
| Karta Produkty je úplne zaplnená | Každý konfigurovaný sprievodný produkt sa zobrazí, vrátane riadkov s nulovým zapojením (zobrazenia zaplnia riadky bez kliknutí). |
| Deduplikácia funguje             | Počty zostávajú stabilné, keď znova odošlete rovnaké zobrazenie/kliknutie.                                                       |

## Riešenie problémov (špecifiká pre Nakupovateľný banner)

| Symptóm                                                           | Riešenie                                                                                                                                                                    |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Spojené požadované udalosti produktov neprichádzajú               | Potvrďte, že banner je Banner X so sprievodnými produktmi vo fáze reklamného materiálu a že `productImpression` a `productClick` sa odosielajú s `productCode`/`catalogId`. |
| Zobrazenia sa odosielajú pri každom posunutí/opätovnom vykreslení | Odošlite jedno `productImpression` na produkt a výskyt viditeľnosti; debouncujte.                                                                                           |
| Na karte Produkty sa zobrazujú nesprávne alebo chýbajúce produkty | Pravdepodobne ide o nesúlad `productCode`/`catalogId` s katalógom — zlaďte ID, ktoré odosielate, s feedom katalógu.                                                         |
| Počty kusov v košíku izpovedajú nesprávne                         | Odosielate delty — odošlite absolútny aktuálny `units`.                                                                                                                     |

Všeobecné riešenie problémov s koncovými bodmi nájdete v [Technickú referenciu pre reportovanie udalostí interakcie s reklamou](https://help.citrusad.com/retail-media-interface/integration/sk/data-api/api-overview/ad-interaction-events-reporting) sekcii riešenia problémov.


---

# 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/integrate-banner-x-shoppable-banner-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.