> 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/integrate-banner-x-shoppable-banner-interaction-reporting.md). # Integrare la segnalazione delle interazioni per Banner X Shoppable Banner Un banner acquistabile è un Banner X annuncio con più hotspot per prodotti correlati in un unico posizionamento. Una volta che questi eventi affluiscono, il report della campagna scompone le prestazioni del banner per ciascun prodotto correlato (impressioni, clic e CTR, oltre alle azioni del carrello se integrate) anziché mostrare un unico totale a livello di banner. Questa guida copre solo i tipi di interazione con i banner acquistabili. Per l'endpoint, l'autenticazione, i campi principali (`adId`, `timestamp`, ID di tracciamento), le dinamiche dei beacon, la deduplica e i test, consulta la [Riferimento tecnico per la segnalazione degli eventi di interazione con gli annunci](https://help.citrusad.com/retail-media-interface/integration/it/data-api/api-overview/ad-interaction-events-reporting). ## Prerequisiti | Prerequisito | Scopo | | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Leggi la [Riferimento tecnico](https://help.citrusad.com/retail-media-interface/integration/it/data-api/api-overview/ad-interaction-events-reporting) | Conferma l'endpoint, l'autenticazione, i campi principali e i requisiti di deduplica. | | Prodotti correlati configurati sul Banner X materiale creativo | Garantisce che le interazioni a livello di prodotto possano essere attribuite al materiale creativo. | | Gli annunci erogati restituiscono un `adId` | Collega ogni evento all'istanza dell'annuncio erogato. | | `productCode` e `catalogId` disponibile per ciascun prodotto correlato | Identifica il prodotto e il catalogo utilizzati nella reportistica. | | Regola di visualizzabilità concordata per i riquadri dei prodotti | Definisce quando un riquadro di prodotto viene considerato visto per `productImpression`. | | ID di tracciamento coerente per sessione pubblicitaria | Supporta l'attribuzione e la deduplica utilizzando `sessionId`, `customerId`, or `dtmToken`. | ## Tipi di interazione per la reportistica dei banner acquistabili Questi sono `adInteraction` eventi (no `moduleId`). Invia i campi principali più i campi chiave descritti di seguito. `productImpression` e `productClick` sono i due eventi che sbloccano la scheda Prodotti: inviali entrambi. | `interactionType` | Campi chiave | Quando inviare | Scopo della reportistica | | ------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `productImpression` | `productCode`, `catalogId` | Un riquadro/SKU di prodotto diventa visibile in base alle tue regole di visualizzabilità | Impressioni per singolo prodotto: popola la colonna delle impressioni (e le righe con zero clic) | | `productClick` | `productCode`, `catalogId` | Un acquirente fa clic su un riquadro/SKU di prodotto | Clic per singolo prodotto: alimenta i clic e il CTR | | `creativeClick` | `creativeId` | Clic su un elemento del materiale creativo non legato al prodotto | Coinvolgimento con materiale creativo non legato al prodotto | | `cart` | `productCode`, `catalogId`, `units`, opzionale `conversionValue` | Modifica del carrello dal contesto dell'annuncio | Intenzione di aggiunta al carrello / valore del prodotto | ## Regole di visualizzabilità per `productImpression` | Regola | Guida | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Definisci quando un riquadro viene considerato visto | Concorda una regola di visualizzabilità, ad esempio percentuale di visibilità più tempo sullo schermo, e applicala in modo coerente su web e app. | | Invia le impressioni una sola volta per ciascuna occorrenza di visualizzabilità | Riduci l'oscillazione dello scorrimento e le nuove rendering per evitare che una singola visualizzazione venga conteggiata più volte. | ## Carrello: Invia le unità correnti assolute Invia `cart` a ogni interazione con il carrello: aggiunta iniziale, ogni `+`ogni `−`, e rimozione (ritorno a `0`) — con `units` impostato sul conteggio assoluto delle unità correnti, non su un delta. L'invio nuovamente del totale corrente mantiene i conteggi corretti in fase di deduplica. Aggiungi `conversionValue` quando lo possiedi. {% hint style="info" %} **Esempio** — un acquirente aggiunge un prodotto, lo incrementa due volte, poi lo rimuove:\*\* `cart {units: 1}` → `cart {units: 2}` → `cart {units: 3}` → `cart {units: 0}` {% endhint %} ## Implementazione passo dopo passo ### Passaggio 1 — Acquisisci il contesto dell'annuncio Leggi il valore realizzato `adId` dall'annuncio erogato e `productCode`/`catalogId` per ciascun riquadro correlato. Stabilisci un ID di tracciamento per la sessione e riutilizzalo per impressioni e clic. ### Passaggio 2 — Invia le impressioni del prodotto Quando un riquadro soddisfa la tua regola di visualizzabilità, invia `productImpression` una volta per quel prodotto. ```javascript navigator.sendBeacon( "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" + new URLSearchParams({ adId, interactionType: "productImpression", sessionId, timestamp: new Date().toISOString(), productCode, catalogId }) ); ``` ### Passaggio 3 — Invia un clic sul prodotto ```javascript navigator.sendBeacon( "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" + new URLSearchParams({ adId, interactionType: "productClick", sessionId, timestamp: new Date().toISOString(), productCode, catalogId }) ); ``` ### Passaggio 4 — Invia le modifiche al carrello In caso di aggiunta/aggiornamento, invia `cart` con il valore assoluto attuale `units` per quel prodotto (e `conversionValue` se lo possiedi) — consulta la regola del carrello sopra. ## Esempi di richieste URL GET completi (andati a capo per leggibilità — invia come una singola stringa di query codificata). ### Impressione del prodotto ```http GET https://integration.retailer.citrusad.com/v1/events/ad/interaction ?adId=shotgun_0001 ×tamp=2026-05-20T10:15:00Z &sessionId=12345gsyuhf-6678ghsj &productCode=prod-00001-01 &catalogId=catlg-custom-DAA001 &interactionType=productImpression ``` ### Clic sul prodotto ```http GET https://integration.retailer.citrusad.com/v1/events/ad/interaction ?adId=shotgun_0001 ×tamp=2026-05-20T10:15:30Z &sessionId=12345gsyuhf-6678ghsj &productCode=prod-00001-01 &catalogId=catlg-custom-DAA001 &interactionType=productClick ``` ### Aggiunta al carrello da annuncio ```http GET https://integration.retailer.citrusad.com/v1/events/ad/interaction ?adId=shotgun_0001 ×tamp=2026-05-20T10:16:00Z &customerId=cust-abc-123 &productCode=prod-00001-01 &catalogId=catlg-custom-DAA001 &interactionType=cart &units=2 &conversionValue=29.99 ``` ## Come si presenta un risultato corretto | Controllo | Dettaglio | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Gli eventi restituiscono HTTP 200 | `productImpression` e `productClick` restituiscono HTTP 200 in PRE/QA. | | La scheda Prodotti è completamente popolata | Ogni prodotto correlato configurato viene visualizzato, comprese le righe a coinvolgimento zero (le impressioni popolano le righe con zero clic). | | La deduplicazione funziona | I conteggi rimangono stabili quando si attiva nuovamente la stessa impressione/clic. | ## Risoluzione dei problemi (specifiche del Banner Shoppable) | Sintomo | Soluzione | | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Gli eventi di prodotto richiesti non arrivano | Conferma che il banner sia Banner X con prodotti correlati nella fase del materiale creativo e che `productImpression` e `productClick` si attivino con `productCode`/`catalogId`. | | Impressioni che si attivano a ogni scorrimento/nuovo rendering | Attivane uno `productImpression` per prodotto per ciascuna occorrenza di visualizzabilità; applica il debouncing. | | La scheda Prodotti mostra prodotti errati o mancanti | Probabile mancata corrispondenza con `productCode`/`catalogId` il catalogo — riconcilia gli ID inviati con il feed del catalogo. | | Le unità del carrello sembrano errate | Stai inviando delta — invia il valore assoluto attuale `units`. | Per la risoluzione generale dei problemi con gli endpoint, consulta la [Riferimento tecnico per la segnalazione degli eventi di interazione con gli annunci](https://help.citrusad.com/retail-media-interface/integration/it/data-api/api-overview/ad-interaction-events-reporting) sezione di risoluzione dei problemi. --- # 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/integrate-banner-x-shoppable-banner-interaction-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.