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

# Hirdetésinterakciós események jelentése

A hirdetési interakciós események jelentése egy további jelentési réteget biztosít a kampányokhoz, amely lehetővé teszi Önnek és márkáinak, hogy megértsék, hogyan lépnek interakcióba az ügyfelek a hirdetéseivel.

Vásárolható Banner X és Videó Banner X az integrációk eseményeket küldenek ugyanarra a végpontra, ugyanazzal a szállítással, hitelesítéssel és alapvető mezőkkel. Olvassa el ezt egyszer, majd kövesse az engedélyezni kívánt jelentéshez tartozó útmutatót.

## Hogyan illeszkednek egymáshoz az integrációk

Az interakciós végpont három jelentési eredményt támogat. Ez az oldal a közös hivatkozás; mindegyik eredménynek megvan a maga feladatútmutatója, amely visszamutató hivatkozást tartalmaz ide a technikai részletekért.

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

| Eredmény           | Végpont        | Interakciótípusok (összegzés)                                         |
| ------------------ | -------------- | --------------------------------------------------------------------- |
| Vásárolható Banner | ad/interaction | productImpression, productClick, creativeClick, cart                  |
| Videó              | ad/interaction | videoKreatív anyagView, videoPlay, quartiles, videoComplete, controls |

## Mielőtt hozzákezdene (közös előfeltételek)

| Előfeltétel                                                                                         | Cél                                                                                                 |
| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Kereskedői névtér / katalógus biztosítva és az integrációs alap-URL kiadva                          | Megerősíti, hogy a kereskedői környezet készen áll az interakciós események fogadására.             |
| A megjelenített hirdetések egy megvalósult adId                                                     | Lhetővé teszi, hogy az egyes események a megjelenített hirdetéshez kapcsolódjanak.                  |
| Katalógusazonosítók (productCode, catalogId) elérhetők a hirdetési kontextusban; videoId a videóhoz | Biztosítja a vonatkozó jelentési útmutató által igényelt termék- vagy videókontextust.              |
| Konzisztens követési azonosítók (sessionId, customerId, vagy dtmToken) hirdetési munkamenetenként   | Engedélyezi az attribúciót és az deduplikációt az ugyanabban a munkamenetben lévő események között. |
| Jelentéskészítés engedélyezése megerősítve a fiókhoz                                                | Biztosítja, hogy az elfogadott események átfolyhassanak a jelentési kimenetekre.                    |

### Végpont és szállítás

* Metódus:\*\* HTTPS `GET` lekérdezési paraméterekkel; nincs kérés törzs.
* Végpont: `GET https://integration.{retailer}.citrusad.com/v1/events/ad/interaction`
* Válasz: `HTTP 200` elfogadáskor, `HTTP 400` érvényesítési hiba esetén, `5xx` platformhiba esetén.

### Hitelesítés és biztonság

* Fire-and-forget:\*\* használjon `navigator.sendBeacon`, egy 1×1-es képet, vagy `fetch(…, { keepalive: true })` hogy az események túléljék az oldal elhagyását.
* **Ne próbálja újra a HTTP 400 hibaüzenetet** — ez hibás formátumú, és újra el fog bukni. Ehelyett javítsa a kérést.
* **URL-kódoljon minden értéket**, különösen a hozzájárulási karakterláncot és az URL mezőket.

### Alapvető mezők (minden esemény)

| Mező                                    | Típus  | Kötelező         | Leírás                                                                                                                            | Elfogadott értékek                  |
| --------------------------------------- | ------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `adId`                                  | string | Igen             | Megvalósult hirdetésazonosító a megjelenített hirdetésből                                                                         | —                                   |
| `interactionType`                       | string | Igen             | Esemény típusa (kis- és nagybetűkre érzékeny camelCase)                                                                           | Lásd az eredményenkénti útmutatókat |
| `timestamp`                             | string | Igen             | Esemény ideje (ISO 8601; használja a UTC-t vagy a kereskedői helyi időt konzisztensen)                                            | ISO 8601                            |
| `sessionId` / `customerId` / `dtmToken` | string | Igen (bármelyik) | Követési azonosító — legalább egy kötelező; ha mindegyik hiányzik, az esemény nem tulajdonítható hozzá, és visszautasításra kerül | —                                   |

Használjon újra egy követési azonosítót a teljes hirdetési munkamenethez, és használja ugyanazt a `adId` az adott megjelenített hirdetés minden eseményénél. Mindegyik `interactionType` egy adott jelentési mutatóhoz rendelhető hozzá — lásd az eredményenkénti útmutatót az egyes típusok „jelentési céljáról”.

### Azonosítók

Az azonosítók, amelyek az eseményeket a hirdetésekhez, termékekhez és munkamenetekhez kötik. Az eseményenkénti mezőkövetelmények az egyes útmutatókban találhatók; ez a közös definíciója annak, hogy az egyes azonosítók honnan származnak.

| Azonosító                               | Mi ez                             | Honnan származik                            | Használja                 |
| --------------------------------------- | --------------------------------- | ------------------------------------------- | ------------------------- |
| `adId`                                  | Megvalósult hirdetés-ID           | A kiszolgált hirdetés válasza               | Minden esemény            |
| `productCode` / `catalogId`             | SKU + annak katalógusterjedelme   | Kereskedői katalógus / hirdetési kontextus  | Termék- és kosáresemények |
| `videoId`                               | Stabil videóeszköz-ID             | A videó kreatív anyag                       | Videóesemények            |
| `creativeId`                            | Nem termékjellegű kreatív elem-ID | A kreatív anyag                             | `creativeClick`           |
| `sessionId` / `customerId` / `dtmToken` | Követési ID (bármelyik)           | Kereskedői munkamenet / bejelentkezés / DTM | Minden esemény            |

### Megvalósítási minta (Beacon)

Használjon egy 1×1-es képet, `fetch` ezzel: `keepalive`, or `navigator.sendBeacon` a teljes GET URL-re irányítva. Ne hagyatkozzon a választörzs elemzésére a felhasználói élményhez. Ugyanaz a segéd szolgálja ki mindhárom integrációt — az eredményenkénti útmutatók csak abban különböznek, hogy melyik `interactionType` és mezőket adja át.

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