Registra le origini di attribuzione

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

Una sorgente di attribuzione è un evento correlato all'annuncio (un clic o una visualizzazione) a cui una tecnologia pubblicitaria può allegare i seguenti tipi di informazioni:

• Dati dei report contestuali, come l'ID creatività annuncio, informazioni sulla campagna o sulla località geografica.
• Una destinazione di conversione, ovvero 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 o i clic sugli annunci, a cui il browser attribuisce le conversioni.

Metodi di registrazione

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

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

In questo modo vengono generate richieste di rete a cui devi rispondere con un'intestazione di risposta HTTP di registrazione dell'origine.

Registra le origini per i clic o le visualizzazioni

Per registrare un'origine 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 di registrazione della sorgente. Una volta ricevuta la richiesta, rispondi con l'intestazione Attribution-Reporting-Register-Source. In questa intestazione, specifica la configurazione di Attribution Reporting scelta. Questo passaggio è lo stesso sia per i clic che 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 i dettagli sui casi in cui sono richiesti, 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 della fonte

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 ancoraggio

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 l'esempio di codice.

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 errata del parametro.

Codifica nel seguente modo:

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 di seguito 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 l'origine 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 degli URL fa sì che il browser avvii una richiesta di recupero keep-alive separata, una per ogni URL, che include l'intestazione della richiesta Attribution-Reporting-Eligible.

Questa opzione è utile se vuoi effettuare la registrazione della fonte rispondendo a una richiesta separata dalla richiesta principale dell'elemento.

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

Per registrare un'origine 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 un copione

<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 fai per i clic. Ad esempio, per un'immagine o uno script , puoi impostare l'URL o gli URL 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 in modo efficace ciò che farebbe 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 per i clic e le visualizzazioni è rispondere con l'intestazione Attribution-Reporting-Register-Source.

Per ulteriori informazioni, consulta l'esempio di codice.

Dopo aver ricevuto la 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 convertita in stringa, l'intestazione ha il seguente aspetto:

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

Passaggi successivi

Scopri come registrare i trigger di attribuzione.