Registra le origini di attribuzione

Scopri come registrare le origini per attribuire i clic e le visualizzazioni agli eventi appropriati.

Un'origine attribuzione è un evento correlato all'annuncio (un clic o una visualizzazione), a cui una tecnologia pubblicitaria può associare i seguenti tipi di informazioni:

• Dati dei report contestuali, ad esempio l'ID creatività dell'annuncio, informazioni sulla campagna o sulla località.
• Una destinazione di conversione, ad esempio il sito in cui prevedi che l'utente effettui una conversione.

Se segui i passaggi descritti in questo documento, puoi registrare le sorgenti, ovvero le impressioni degli annunci o i clic, a cui il browser attribuisce le conversioni.

Metodi di registrazione

Per registrare le origini di attribuzione, utilizza elementi HTML o chiamate JavaScript:

• Tag <a>
• Tag <img>
• Tag <script>
• fetch chiamata
• XMLHttpRequest
• window.open chiamata

Vengono generate richieste di rete a cui rispondi con un'intestazione della risposta HTTP di registrazione della sorgente.

Registra le sorgenti per i clic o le visualizzazioni

Per registrare un'origine di attribuzione per i clic o le visualizzazioni, segui i passaggi descritti qui. Di seguito sono riportati i passaggi completi. Ecco il riepilogo:

1. Avvia la registrazione dell'origine. Utilizza un elemento HTML o una chiamata JavaScript per effettuare una richiesta. Questo passaggio è diverso per i clic e le visualizzazioni, come noterai nelle sezioni seguenti.

2. Completa la registrazione della sorgente rispondendo con l'intestazione della registrazione della sorgente. Al ricevimento della richiesta, rispondi con l'intestazione Attribution-Reporting-Register-Source. In questa intestazione, specifica la configurazione dei report sull'attribuzione scelta. Questo passaggio è lo stesso sia per i clic sia per le visualizzazioni.

   Esempio per i report di riepilogo:

   {
     "aggregation_keys": {
       "campaignCounts": "0x159",
       "geoValue": "0x5"
     },
     "aggregatable_report_window": "86400",
     "destination": "https://example.com"
   }
   

   Esempio per i report a livello di evento:

   {
     "source_event_id": "12340873456",
     "destination": "[eTLD+1]",
     "expiry": "[64-bit signed integer]",
     "priority": "[64-bit signed integer]",
     "event_report_window": "[64-bit signed integer]"
   }
   

Attributi obbligatori e facoltativi

Quando utilizzi elementi HTML o effettui chiamate JavaScript per registrare le origini, potresti dover utilizzare attributionsrc o attributionReporting. Per informazioni dettagliate su quando sono obbligatori, consulta la tabella seguente.

Quando attributionsrc è facoltativo, il suo utilizzo indica che la richiesta è idonea per i report sull'attribuzione. Se utilizzi attributionsrc, il browser invia l'intestazione Attribution-Reporting-Eligible. È utile anche per la misurazione da app a web: se è presente attributionsrc, il browser invia l'intestazione Attribution-Reporting-Support.

Passaggio 1: avvia la registrazione dell'origine

Il passaggio 1 è diverso per i clic e le visualizzazioni.

Per registrare un'origine attribuzione per un clic, puoi utilizzare un tag <a> o JavaScript window.open().

Utilizzo di un'ancora

Aggiungi attributionsrc ai tag <a> esistenti per i quali vuoi misurare le impressioni o i clic:

<a href="https://shoes.example/..." attributionsrc>Click me</a>

Per ulteriori informazioni, consulta il codice di esempio.

Utilizzo di uno script

Chiama window.open() con attributionsrc:

window.open(
  "https://shoes.example/...",
  "_blank",
  "attributionsrc");

Per essere preso in considerazione, questo metodo deve essere chiamato entro 5 secondi dall'interazione dell'utente.

Anziché aggiungere attributionsrc da solo, per un'immagine o uno script puoi specificare un singolo valore URL:

<a href=... attributionsrc="https://a.example/register-source">Click me</a>

Nel caso di JavaScript, se assegni un valore a attributionsrc, assicurati di codificare l'URL nel caso in cui contenga caratteri speciali come = che causerebbero un'analisi non corretta del parametro.

Codifica come segue:

const encodedUrl = encodeURIComponent(
  "https://adtech.example/attribution_source?ad_id=...");
window.open(
  "https://shoes.example/landing",
   "_blank",
   `attributionsrc=${encodedUrl}`);

attributionsrc può anche accettare un elenco di URL separati da spazi, come illustrato qui con un tag <a>:

<a href=... attributionsrc="https://a.example/register-source
  https://b.example/register-source">Click me</a>

o come in questo caso utilizzando window.open().

window.open("...", "_blank", `attributionsrc=${encodedUrl1}
  attributionsrc=${encodedUrl2}`)

In questi casi, entrambi gli URL ricevono richieste attributionsrc idonee per le sorgenti di navigazione (richieste che includono l'intestazione Attribution-Reporting-Eligible).

attributionsrc con o senza un valore

Come hai visto in precedenza, puoi specificare attributionsrc senza un URL. Puoi anche specificare un singolo URL. Inoltre, puoi utilizzare un elenco di URL separati da spazi.

L'utilizzo di URL fa sì che il browser avvii una richiesta di recupero keepalive separata, una per ogni URL, che include l'intestazione della richiesta Attribution-Reporting-Eligible.

Questa operazione è utile se vuoi eseguire la registrazione dell'origine rispondendo a una richiesta distinta dalla richiesta principale dell'elemento.

Ad esempio, se devi registrare le sorgenti per i clic su un elemento di ancoraggio, potresti non avere il controllo della destinazione. In questo caso, ti consigliamo di scegliere una configurazione in cui invii l'intestazione di registrazione della sorgente come risposta a una richiesta distinta dalla navigazione e che puoi controllare completamente. Specificando un valore esplicito per attributionsrc, indichi al browser di effettuare la richiesta aggiuntiva e di configurarne la destinazione.

Per registrare un'origine di attribuzione per una visualizzazione, puoi utilizzare un tag immagine o script a cui aggiungere l'attributo attributionsrc.

In alternativa, puoi utilizzare JavaScript fetch() o XMLHttpRequest().

Con un'immagine

<img attributionsrc
src="https://adtech.example/attribution_source?ad_id=...">

Con uno script

<script attributionsrc
  src="https://adtech.example/attribution_source?ad_id=..."></script>

Se vuoi, puoi specificare un valore URL per attributionsrc nello stesso modo in cui lo fai per i clic. In altre parole, per un'immagine o uno script , puoi impostare l'URL o gli URL di attributionsrc nel seguente modo:

Con un singolo URL:

<img attributionsrc="https://adtech.example/attribution_source?ad_id=123">

Con un elenco di URL:

<img attributionsrc="https://a.example/register-source
  https://b.example/register-source">

Utilizzo di fetch() o XMLHttpRequest()

Questo codice simula efficacemente il comportamento di una richiesta HTML con attributionsrc:

const attributionReporting = {
  eventSourceEligible: true,
  triggerEligible: false,
};

// Optionally set keepalive to make sure the request outlives the page.
window.fetch("https://adtech.example/attribution_source?my_ad_id=123",
  { keepalive: true, attributionReporting });

const attributionReporting = {
  eventSourceEligible: true,
  triggerEligible: false,
};

const req = new XMLHttpRequest();
req.open("GET", url);
req.setAttributionReporting(attributionReporting);
req.send();

Passaggio 2: rispondi con l'intestazione (clic e visualizzazioni)

Il passaggio successivo sia per i clic sia per le visualizzazioni è rispondere con l'intestazione Attribution-Reporting-Register-Source.

Per ulteriori informazioni, consulta il codice di esempio.

Al ricevimento della richiesta del browser sul server, rispondi e includi nella risposta l'intestazione Attribution-Reporting-Register-Source.

res.set(
  "Attribution-Reporting-Register-Source",
  JSON.stringify({
    // Use source_event_id to map it to any granular information
    // you need at ad-serving time
    source_event_id: "412444888111012",
    destination: "https://advertiser.example",
    // Optional fields
    expiry: "604800",
    priority: "100",
    debug_key: "122939999"
  })
);

Una volta sottoposta a stringificazione, l'intestazione avrà il seguente aspetto:

{"source_event_id":"412444888111012","destination":"https://advertiser.example","expiry":"604800","priority":"100","debug_key":"122939999"}

Passaggi successivi

Scopri come registrare gli attivatori di attribuzione.