> 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/brand-pages/brand-page-retailer-integration-guide/tracking-attribution.md). # Tracciamento e attribuzione ## Come comporre un URL di tracciamento La risposta fornisce tre origini da combinare: * A livello di pagina `trackers.impression`: ad esempio, un'impressione di pagina utilizza `type: "impression"` e `params` incluso `ts` e `iabConsentString`. * Condiviso `trackingTemplates`: un set di modelli URL `client`(relativo) e `server` (assoluto), contenenti già i parametri di query della sessione e del posizionamento. * Per nodo `trackers.click` e/o `trackers.addToCart` su un modulo, una riga o un elemento della galleria: `type`+ `params` per quel determinato evento (ad esempio, `modId`, `rurl`, `productCode`). ### Quale modello? Utilizza il nodo `tracking.type` per cercare `trackingTypes.`. Questo definisce le chiavi `client.*` e `server.*` valide per tale interazione (ad esempio, per il link: `client.clickRedirect`, `client.clickEvent`, `server.clickEvent)`. ### Client vs Server * Client (`trackingTemplates.client.*`): i valori sono percorsi relativi (incluse le stringhe di query). Anteponi l'URL di base del tuo reverse proxy (`BASEURL`). * Server (`trackingTemplates.server.`): i valori sono modelli di URL assoluti sull'host di tracciamento Epsilon . Componi l'URL finale nello stesso modo di C2S: modello + `"&"` + `queryString(trackers.params)`. {% hint style="info" %} Non modificare l'host o il percorso del modello e non inviare chiamate S2S tramite il reverse proxy. {% endhint %} ### Esempi pratici (pseudocodice) #### Click C2S per una CTA HERO ``` url = BASEURL + trackingTemplates.client.clickRedirect + "&" + queryString(trackers.click.params) ``` #### Impressione di pagina S2S ``` url = trackingTemplates.server.impressionEvent + "&" + queryString(trackers.impression.params) ``` #### Aggiunta al carrello S2S per una riga di prodotto ``` url = trackingTemplates.server.addToCartEvent + "&" + queryString(trackers.addToCart.params) ``` Sostituzione macro * Sostituisci {TS} con il timestamp corrente in millisecondi, {RURL} con la destinazione codificata in formato URL e `{TCF}` con la stringa TCF v2 corrente della tua CMP prima dell'invio. * Per l'aggiunta al carrello, sostituisci anche {QTY} con la quantità assoluta di quello SKU nel carrello al momento dell'invio (non una variazione) e {CONVERSION\_VALUE} con il valore monetario assoluto di tali articoli (quantità × prezzo unitario, meno eventuali sconti applicati). {% hint style="info" %} * Solo `trackingTemplates.client.impressionPixelUrls` sono veri pixel (GIF 1×1). * `clickRedirect` è un endpoint di reindirizzamento 302. * `clickEvent` e `addToCartEvent` sono beacon di evento che restituiscono 204 No Content. {% endhint %} {% hint style="danger" %} Non inviare sia C2S che S2S per lo stesso evento logico (ad esempio, non inviare sia un evento di click C2S che una notifica di click S2S per lo stesso click). {% endhint %} ## Tracciamento – Client-to-Server (C2S) Il tracciamento C2S viene implementato nel browser utilizzando URL composti. Anteponi `BASEURL` ai percorsi in `trackingTemplates.client` e aggiungi l'opportuno `trackers.params` (vedi [Come comporre un URL di tracciamento](#how-to-compose-a-tracking-url)). Solo `client.impressionPixelUrls` sono pixel (GIF 1×1). Gli altri modelli client non sono pixel: * `client.clickRedirect`: endpoint di reindirizzamento 302. Epsilon registra il click e reindirizza il browser alla rurl decodificata. Utilizzalo come destinazione di navigazione del browser. * `client.clickEvent`: il **beacon di evento** restituisce 204 No Content). Invia utilizzando `navigator.sendBeacon` or `fetch({ keepalive: true })`. Non eseguire il rendering come ``. * `client.addToCartEvent`: **beacon di evento** (restituisce 204). Utilizza lo stesso schema di invio di `clickEvent`. ### Fasi di implementazione 1. Esegui il rendering del contenuto della pagina del brand restituito dall'API. 2. Dopo il rendering, invia i pixel di impressione nel browser (tutte le voci in `trackingTemplates.client.impressionPixelUrls`, come immagini 1×1). 3. Quando un utente fa click su un nodo tracciabile, è possibile:\ (a) reindirizzare tramite l'URL `client.clickRedirect` composto, oppure\ (b) inviare l'URL `client.clickEvent` composto come beacon di evento e navigare autonomamente verso la destinazione.\ Utilizza l'una o l'altra opzione per ogni click, non entrambe. ### Pixel di impressione Dopo il rendering della pagina del brand, invia ciascun percorso in `trackingTemplates.client.impressionPixelUrls` come immagine 1×1, (vedi[ Come comporre un URL di tracciamento](#how-to-compose-a-tracking-url)). ```html ``` Passaggi: 1. Per ogni stringa in `trackingTemplates.client.impressionPixelUrls`, anteponi il tuo `BASEURL` (ad esempio, `https://www.retailer.com/epsilon`). 2. Aggiungi `&` + `queryString(trackers.impression.params)`, sostituendo `{TS}` con il timestamp corrente in millisecondi e `{TCF}` con la stringa di consenso corrente dalla tua CMP. 3. Attiva come 1×1 `< img src="...">` nel browser (o equivalente). ### Monitoraggio dei clic #### Opzione A: Reindirizzamento del clic (`client.clickRedirect`) Naviga l'utente attraverso l'URL composto. Epsilon registra il clic e risponde con **HTTP 302** all'URL decodificato `rurl`. Questo endpoint è **solo GET**, e `rurl` è obbligatorio; #### Opzione B: Beacon di evento di clic (`client.clickEvent`) Attiva come beacon e naviga autonomamente. Accetta GET o POST, restituisce 204 No Content. Non è un'immagine; non eseguire il rendering come``. ### Aggiunta al carrello (C2S) Attiva `trackingTemplates.client.addToCartEvent` come beacon di evento (non come pixel) quando l'utente aggiunge un prodotto al carrello. Accetta GET o POST, restituisce 204 No Content. {% hint style="info" %} Non combinare l'aggiunta al carrello C2S e S2S per la stessa azione del carrello. {% endhint %} ## Monitoraggio – Server‑to‑Server (S2S) Il monitoraggio S2S è implementato sul tuo backend. Componi gli URL nello stesso modo di C2S: inizia dalla stringa `trackingTemplates.server` appropriata, quindi aggiungi `trackers.params`. I modelli del server sono già assoluti — non c'è alcun `BASEURL`da anteporre. (vedi [Come comporre un URL di tracciamento](#how-to-compose-a-tracking-url)). {% hint style="info" %} Non modificare l'host o il percorso dal modello del server e non inviare richieste S2S tramite il tuo reverse proxy. {% endhint %} ### Quando utilizzare il monitoraggio S2S * La tua architettura richiede l'attivazione degli eventi lato server. * Hai bisogno del monitoraggio in ambienti in cui i pixel lato client non sono affidabili. * Vuoi combinare le strategie - ad es. impression C2S + aggiunta al carrello S2S. Questo è supportato, ma non attivare mai sia C2S che S2S per lo stesso evento. ### Notifica di impression S2S Dopo che la pagina del brand è stata renderizzata, il tuo server invia una richiesta **GET** o **POST** all'URL dell'impression composto: `trackingTemplates.server.impressionEvent` + `trackers.impression.params` (sostituisci `{TS}` e `{TCF}` prima dell'invio). ### Notifica di clic S2S Componi: `trackingTemplates.server.clickEvent` + `trackers.click.params` (sostituisci `{TS}`, {RURL}, e `{TCF}`), quindi invia GET o POST. ### Notifica di aggiunta al carrello S2S Componi: `trackingTemplates.server.addToCartEvent` + `trackers.addToCart.params` (sostituisci `{TS}`, {QTY}, {CONVERSION\_VALUE}, e `{TCF}`), quindi invia GET o POST. ### Parametri S2S | Parametro | Origine | Note | | ----------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `catalogId`, `sessionId`, `customerId`, `dtmId`, `placementId`, `lsid`, `utcOffset` | `trackingTemplates` stringhe di query | Conserva questi valori così come sono quando attivi la richiesta. Non rimuoverli o modificarli. | | `modId` | `trackers..params` | Identificatore del modulo di contenuto o della riga. | | `ts` | `trackers..params` | Sostituisci `{TS}` con il timestamp corrente in millisecondi prima di attivare la richiesta. | | `iabConsentString` | `trackers..params` | Sostituisci `{TCF}` con la stringa di consenso TCF v2 corrente dalla CMP prima di attivare la richiesta. Se un valore è già fornito, utilizzalo così com'è. | | `rurl` | `trackers..params` | Destinazione di reindirizzamento codificata in formato URL. Sostituisci `{RURL}` se presente. | | `productCode`, `sellerId` | `trackers..params` | Valori derivati dai nodi prodotto. | | `qty` | `trackers.addToCart.params` | Sostituisci `{QTY}` con la quantità assoluta dello SKU nel carrello al momento dell'attivazione della richiesta. Non utilizzare la variazione di quantità. | | `conVal` | `trackers.addToCart.params` | Sostituisci `{CONVERSION_VALUE}` con il valore monetario totale degli articoli (quantità × prezzo unitario, meno eventuali sconti applicabili). | ## Riferimento macro | Simbolo | Descrizione | Trovato in | Sostituisci con | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------- | | `BASEURL` (il tuo prefisso) | URL di base del tuo sito con protocollo e percorso proxy: anteponi a ciascun `trackingTemplates.client.*` percorso. | Tracciamento C2S | `https://www.retailer.com/epsilon` | | `{TS}` | Timestamp per la prevenzione della cache (millisecondi) | `trackers..params` | `1737485823910` | | `{RURL}` | Destinazione del reindirizzamento codificata in URL | `trackers..params.rurl` | `https%3A%2F%2Fwww.retailer.com%2Fprodukt%2F9221200653341` | | `{TCF}` | Segnaposto per la stringa di consenso IAB TCF v2. Presente quando `regs.consent` è stato omesso nella richiesta. | `trackers..params.iabConsentString` | Stringa TC corrente dalla tua CMP, ad es. tramite `__tcfapi` `getTCData` → `tcString` | | `{QTY}` | Quantità assoluta di questo SKU nel carrello al momento dell'attivazione (non un delta; ad es. se l'acquirente ne aveva 1 e ne aggiunge un altro, invia `2`). | `trackers.addToCart.params.qty` | `2` | | `{CONVERSION_VALUE}` | Valore monetario assoluto di tali articoli: quantità × prezzo unitario, meno eventuali sconti applicati. | `trackers.addToCart.params.conVal` | `49.99` | | `{RURL_KID}` | ID della chiave di firma del reindirizzamento. Presente in `trackers.click.redirectParams` quando la firma del reindirizzamento della piattaforma è abilitata. | `trackers.click.redirectParams.rurlKid` | ID della chiave di firma restituito dall'endpoint batch sign | | `{RURL_SIG}` | Firma del reindirizzamento. Presente in `trackers.click.redirectParams` quando la firma del reindirizzamento della piattaforma è abilitata. | `trackers.click.redirectParams.rurlSig` | Firma Ed25519 (base64url) restituita dall'endpoint batch sign | ### Riferimento per la codifica URL Durante la codifica di `{RURL}`, utilizza la codifica percent-encoding standard: | Carattere | Codifica come | | --------- | ------------- | | `:` | `%3A` | | `/` | `%2F` | | `?` | `%3F` | | `=` | `%3D` | | `&` | `%26` | ### redirectParams e firma del reindirizzamento Quando la firma del reindirizzamento della piattaforma è abilitata, `trackers.click` può includere un oggetto `redirectParams`insieme a `params`. Le chiavi in `7`vengono unite solo negli `client.clickRedirect` URL, non in `clickEvent`o in qualsiasi URL del server. Due casi: **Destinazioni di link incorporate** (URL integrato in `params.rurl`): la piattaforma firma il reindirizzamento al momento dell'erogazione ed emette valori letterali `rurlKid`e `rurlSig`in `redirectParams`. Allega questi valori così come sono all'URL `clickRedirect` . **Reindirizzamenti gestiti dal retailer** (`params.rurl` è {RURL}): `redirectParams` contiene le macro {RURL\_KID} e {RURL\_SIG}. Chiama l'endpoint batch sign (`redirectSigning.url` dalla risposta) per ottenere l'ID chiave e la firma per il tuo URL di destinazione, quindi sostituisci prima di allegare. L'oggetto di primo livello `redirectSigning`, quando presente, fornisce l'URL dell'endpoint `POST /ads/v3/redirect/sign` batch e il limite batch di `maxUrls`. Contatta Epsilon per confermare se la firma del reindirizzamento è abilitata per la tua integrazione. ### Composizione di clickRedirect con redirectParams: ``` BASEURL + trackingTemplates.client.clickRedirect + "&" + queryString(trackers.click.params) + "&" + queryString(trackers.click.redirectParams) ```
## Guida di stile Prima di abilitare le Brand Pages sul tuo sito, dobbiamo acquisire l'identità visiva del tuo sito. Compila la tabella sottostante con i tuoi valori di design. Il nostro team la utilizzerà per configurare l'esperienza di anteprima della brand page. #### Logo | Campo | Descrizione | Il tuo valore | | ------------ | ------------------------------------- | ------------- | | URL del logo | URL del logo del tuo sito (SVG o PNG) | | #### Colori | Campo | Descrizione | Il tuo valore | | --------------------------- | --------------------------------------------------------------- | ------------- | | Colore primario | Colore principale del brand (hex) | | | Colore di sfondo | Colore di sfondo della pagina (hex) | | | Colore della superficie | Colore di sfondo della scheda/sezione (hex) | | | Colore del testo primario | Colore del testo principale (hex) | | | Colore del testo secondario | Colore del testo attenuato (hex) | | | Testo su colore primario | Colore del testo utilizzato su sfondi con colore primario (hex) | | | Colore del bordo | Colore del bordo predefinito (hex) | | #### Tipografia | Campo | Descrizione | Il tuo valore | | ------------------------------------ | ---------------------------------------------------------------------- | ------------- | | Famiglia di font delle intestazioni | Font utilizzato per le intestazioni (ad es. "Google Sans, sans-serif") | | | Famiglia di font del corpo del testo | Font utilizzato per il corpo del testo (ad es. "Roboto, sans-serif") | | | Dimensione del font di base | Dimensione predefinita del font del corpo del testo (ad es. 16px) | | #### Pulsanti | Campo | Descrizione | Il tuo valore | | -------------------------------------- | ----------------------------------------------------------------- | ------------- | | Sfondo del pulsante primario | Colore di sfondo per i pulsanti primari | | | Colore del testo del pulsante primario | Colore del testo per i pulsanti primari | | | Raggio del bordo del pulsante primario | Arrotondamento degli angoli (ad es. 8px) | | | Stile del pulsante secondario | Descrive l'aspetto del pulsante secondario (outline, ghost, ecc.) | | ## Requisiti di contenuto del modulo Le Brand Page sono composte da moduli di contenuto. Per ciascun tipo di modulo, fornisci i vincoli di contenuto richiesti dal tuo sito. Il nostro team li utilizzerà per configurare le regole di convalida dei modelli. ### Moduli IMAGE | Requisito | Descrizione | Il tuo valore | | ---------------------------------- | --------------------------------------------------------------------------- | ------------- | | Larghezza minima | Larghezza minima dell'immagine in pixel (ad es. 1920) | | | Altezza minima | Altezza minima dell'immagine in pixel (ad es. 500) | | | Dimensione massima del file | Dimensione massima del file in MB (ad es. 10). Deve essere inferiore a 4MB. | | | Formati accettati | Formati di immagine accettati (ad es. jpg, png, gif, svg) | | | Caratteri massimi della didascalia | Numero massimo di caratteri per la didascalia dell'immagine, se applicabile | | | `alt`Opzionalità del tag | Se `alt` è richiesto sulle immagini. | | ### Moduli TEXT | Requisito | Descrizione | Il tuo valore | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | Variante | “headline”, “tagline”, “body” o “lines”. Determina lo stile con cui viene visualizzato il testo. | | | Allineamento | “left”, “center” o “right”. Determina l'allineamento orizzontale del testo. | | | Configurazione “Lines” |

Configurazione per la configurazione del testo multilinea (quando variant = lines). Per ogni riga di testo, fornisci quanto segue:

- nome del campo di testo
- “required” o “allowed”?
- se deve essere un collegamento ipertestuale a un altro URL

| | | Caratteri massimi del titolo | Numero massimo di caratteri per il testo del titolo | | | Caratteri massimi della descrizione | Numero massimo di caratteri per il testo della descrizione | | | Caratteri massimi del corpo/piè di pagina | Numero massimo di caratteri per il testo del corpo o del piè di pagina | | | Pulsante CTA | Obbligatorio, opzionale o non necessario? | | | Caratteri massimi del testo della CTA | Numero massimo di caratteri per l'etichetta del pulsante CTA | | ### Moduli PRODUCT\_GRID | Requisito | Descrizione | Il tuo valore | | ------------------------------------------------- | ------------------------------------------------------------ | ------------- | | Prodotti minimi | Numero minimo di prodotti da visualizzare (ad es. 4) | | | Prodotti massimi | Numero massimo di prodotti da visualizzare (ad es. 12) | | | Titolo della sezione | Obbligatorio o opzionale? | | | Caratteri massimi del titolo della sezione | Numero massimo di caratteri per il titolo della sezione | | | Descrizione della sezione | Obbligatorio o opzionale? | | | Caratteri massimi della descrizione della sezione | Numero massimo di caratteri per la descrizione della sezione | | | Pulsante CTA | Obbligatorio, opzionale o non necessario? | | ### Moduli IMAGE\_GALLERY Il modulo Galleria immagini eredita le stesse proprietà di configurazione del modulo IMAGE. Inoltre, accetta le seguenti proprietà specifiche per la galleria: | Requisito | Descrizione | Il tuo valore | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- | | Immagini minime | Numero minimo di immagini della galleria (ad es. 2) | | | Immagini massime | Numero massimo di immagini della galleria (ad es. 4) | | | Titolo della sezione | Se il testo del titolo della sezione è obbligatorio o opzionale. | | | Descrizione della sezione | Se il testo della descrizione della sezione è obbligatorio o opzionale. | | | `alt` Opzionalità del tag | Se `alt` è richiesto sulle immagini. | | | Opzionalità della call-to-action | Se il pulsante o il link della call-to-action è obbligatorio, consentito o disabilitato. | | | Righe di testo aggiuntive |

Per ogni testo aggiuntivo da associare a ciascuna immagine nella galleria immagini, fornire quanto segue:

- nome del campo di testo
- “required” o “allowed”?
Se il testo debba funzionare come collegamento ipertestuale a un altro URL

| | ### Moduli SPLIT\_LAYOUT Il modulo Split Layout consente di visualizzare due moduli affiancati. Attualmente sono supportati solo i moduli Testo e Immagine. Oltre alle singole impostazioni di configurazione per i moduli Testo e Immagine (descritte nelle sezioni precedenti), sono richieste le seguenti proprietà aggiuntive: | Requisito | Descrizione | Il tuo valore | | ------------------ | ---------------------------------------------- | ------------- | | Rapporto di layout | Rapporto tra le colonne (50:50, 33:67 o 67:33) | | ## Identità e privacy ### Identificatori accettabili * ID sessione - identificatore di sessione anonimo (non PII) * ID cliente - identificatore del cliente del retailer (non PII, ad es. hash dell'ID fedeltà) {% hint style="danger" %} Non passare indirizzi email con hash, numeri di telefono o qualsiasi PII in alcun parametro o URL. {% endhint %} ### Requisiti di privacy I retailer devono: * Divulgare il tracciamento delle misurazioni nella loro informativa sulla privacy * Fornire link di rinuncia (opt-out): * NAI: * DAA: ### GDPR / Consenso Passare l'oggetto `regs`su `POST /ads/v3/brand-pages`: * `regs.gdpr`: `1` quando la richiesta è soggetta a GDPR (trattamento UE/SEE/UK in base alla tua informativa); `0`altrimenti. * `regs.consent`Quando `gdpr` is `1`passa la stringa di consenso TCF v2 corrente dalla tua CMP (lo stesso valore che mostreresti ad altri partner pubblicitari). Non inventare o inserire direttamente nel codice una stringa: utilizza ciò a cui l'utente ha acconsentito nel browser / app. * `iabConsentString`Questo appare nei parametri di ogni slot di tracciamento, non in `trackingTemplates`. Quando `regs.consent` è stata fornita, il valore è la stringa TC letterale e non è necessaria alcuna ulteriore azione. * Quando `regs.consent` è stata omessa, il valore è la macro `{TCF}`— sostituisci la stringa TCF v2 corrente dalla tua CMP al momento dell'attivazione prima di inviare qualsiasi richiesta di tracciamento. --- # 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/brand-pages/brand-page-retailer-integration-guide/tracking-attribution.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.