> 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/it/data-api/api-overview/ad-interaction-events-reporting.md).
# Segnalazione degli eventi di interazione con gli annunci
I report sugli eventi di interazione con gli annunci forniscono un ulteriore livello di reportistica per le campagne, consentendo a te e ai tuoi brand di capire in che modo i clienti interagiscono con i tuoi annunci.
Acquistabile Banner X e Video Banner X le integrazioni inviano eventi allo stesso endpoint con gli stessi campi di trasporto, autenticazione e di base. Leggi questa sezione una volta, quindi segui la guida per il report che desideri abilitare.
## In che modo le integrazioni si combinano tra loro
L'endpoint delle interazioni alimenta tre risultati di reportistica. Questa pagina è il riferimento condiviso; ogni risultato ha la propria guida alle attività che rimanda qui per gli aspetti tecnici.
```
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
```
| Risultato | Endpoint | Tipi di interazione (riepilogo) |
| ------------------- | -------------- | -------------------------------------------------------------------------- |
| Banner acquistabile | ad/interaction | productImpression, productClick, creativeClick, cart |
| Video | ad/interaction | videoMateriale creativoView, videoPlay, quartiles, videoComplete, controls |
## Prima di iniziare (requisiti condivisi)
| Requisito | Scopo |
| --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Spazio dei nomi/catalogo del retailer predisposto e URL di base dell'integrazione emesso | Conferma che l'ambiente del retailer è pronto a ricevere gli eventi di interazione. |
| Gli annunci erogati restituiscono un valore realizzato adId | Consente di associare ciascun evento all'annuncio erogato. |
| ID catalogo (productCode, catalogId) disponibili nel contesto dell'annuncio; videoId per i video | Fornisce il contesto del prodotto o del video necessario per la relativa guida di reportistica. |
| ID di tracciamento coerenti (sessionId, customerId, o dtmToken) per ciascuna sessione pubblicitaria | Consente l'attribuzione e la deduplicazione tra gli eventi nella stessa sessione. |
| Abilitazione della reportistica confermata per l'account | Assicura che gli eventi accettati possano confluire nei report generati. |
### Endpoint e trasporto
* Metodo:\*\* HTTPS `GET` con parametri di query; nessun corpo della richiesta.
* Endpoint: `GET https://integration.{retailer}.citrusad.com/v1/events/ad/interaction`
* Risposta: `HTTP 200` in caso di accettazione, `HTTP 400` in caso di errore di validazione, `5xx` in caso di errore della piattaforma.
### Autenticazione e sicurezza
* Fire-and-forget:\*\* usa `navigator.sendBeacon`, un'immagine 1×1, oppure `fetch(…, { keepalive: true })` in modo che gli eventi sopravvivano alla chiusura della pagina.
* **Non riprovare con HTTP 400**: è non valido e meglierà di nuovo. Correggi invece la richiesta.
* **Codifica in formato URL tutti i valori**, in particolare la stringa del consenso e qualsiasi campo URL.
### Campi principali (ogni evento)
| Campo | Tipo | Obbligatorio | Descrizione | Valori accettati |
| --------------------------------------- | ------ | --------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `adId` | string | Sì | ID annuncio realizzato dall'annuncio erogato | — |
| `interactionType` | string | Sì | Tipo di evento (camelCase sensibile al maiuscolo/minuscolo) | Consulta le guide per singolo risultato |
| `timestamp` | string | Sì | Ora dell'evento (ISO 8601; usa UTC o l'ora locale del retailer in modo coerente) | ISO 8601 |
| `sessionId` / `customerId` / `dtmToken` | string | Sì (almeno uno) | ID di tracciamento — è richiesto almeno uno; se mancano tutti, l'evento non può essere attribuito e viene rifiutato | — |
Riusa un singolo ID di tracciamento per l'intera sessione pubblicitaria e riusa lo stesso `adId` per ogni evento relativo a quell'annuncio erogato. Ciascun `interactionType` si associa a una metrica di reportistica specifica — consulta la guida per singolo risultato per lo "scopo di reportistica" di ciascun tipo.
### Identificatori
Gli ID che collegano gli eventi ad annunci, prodotti e sessioni. I requisiti dei campi per singolo evento sono indicati in ciascuna guida; questa è la definizione condivisa dell'origine di ciascun ID.
| Identificatore | Che cos'è | Da dove proviene | Utilizzato da |
| --------------------------------------- | -------------------------------------------------- | ---------------------------------------------- | ------------------------------------- |
| `adId` | ID annuncio realizzato | La risposta dell'annuncio servito | Ogni evento |
| `productCode` / `catalogId` | SKU + il suo ambito del catalogo | Catalogo del retailer / contesto dell'annuncio | Eventi relativi a prodotti e carrello |
| `videoId` | ID risorsa video stabile | Il materiale creativo video | Eventi video |
| `creativeId` | ID elemento del materiale creativo non di prodotto | Il materiale creativo | `creativeClick` |
| `sessionId` / `customerId` / `dtmToken` | ID di tracciamento (qualsiasi) | Sessione / login / DTM del retailer | Ogni evento |
### Modello di implementazione (Beacon)
Utilizza un'immagine 1×1, `fetch` con `keepalive`, or `navigator.sendBeacon` puntata all'URL GET completo. Non fare affidamento sull'analisi del corpo della risposta per l'esperienza utente. Lo stesso helper gestisce tutte e tre le integrazioni — le guide per singolo risultato differiscono solo per quale `interactionType` e per i campi che trasmetti.
```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",
});
```
---
# 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/it/data-api/api-overview/ad-interaction-events-reporting.md?ask=&goal=
```
`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.