Registra le origini di attribuzione

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

Un'origine di attribuzione è un evento relativo all'annuncio (un clic o una visualizzazione) a cui un ad tech può collegare i seguenti tipi di informazioni: - Dati del report contestuale, come l'ID creatività dell'annuncio, informazioni sulla campagna o sull'area geografica. - Una destinazione di conversione, ad esempio il sito in cui prevedi che l'utente effettui la conversione.

Seguendo la procedura descritta in questo documento, puoi registrare le sorgenti (impressioni sugli annunci o clic) a cui il browser attribuisce le conversioni.

Metodi di registrazione

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

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

Questo genera richieste di rete a cui rispondi con un'intestazione della risposta HTTP di registrazione del codice sorgente.

Registra le sorgenti di clic o visualizzazioni

Per registrare un'origine di attribuzione per clic o visualizzazioni, segui la procedura descritta di seguito. Segui i passaggi completi. Ecco il riepilogo:

  1. Avvia la registrazione di origine. Usa 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 dell'origine rispondendo con l'intestazione della registrazione dell'origine. Dopo aver ricevuto la richiesta, rispondi con l'intestazione Attribution-Reporting-Register-Source. Nell'intestazione, specifica la configurazione dei report di attribuzione desiderata. Questo passaggio è lo stesso per i clic e le visualizzazioni.

    Esempio di report di riepilogo:

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

    Esempio di 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 gli elementi HTML o effettui chiamate JavaScript per registrare le origini, potresti dover utilizzare attributionsrc o attributionReporting. Fai riferimento alla tabella seguente per dettagli su quando questi campi sono necessari.

Se 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.

Metodo di registrazione Fonte
Tag <a> (sorgente navigazione)
attributionsrc è obbligatorio.
Tag <img> (origine evento)
attributionsrc è obbligatorio.
Tag <script> (origine evento)
attributionsrc è obbligatorio.
fetch chiamata L'opzione attributionReporting è obbligatoria.
XMLHttpRequest L'opzione attributionReporting è obbligatoria.
window.open() (sorgente navigazione)
attributionsrc è obbligatorio.

Passaggio 1: avvia la registrazione del codice sorgente

Il passaggio 1 è diverso per clic e visualizzazioni. Apri le schede corrispondenti per ogni elemento.

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

Uso 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>

Esamina il codice di esempio per ulteriori informazioni.

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">

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

Codifica nel modo seguente: 

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

attributionsrc può anche utilizzare un elenco di URL separati da spazi, come illustrato qui con un anchor tag:

<!-- With an anchor tag -->
<a href=... attributionsrc="https://a.example/register-source 
  https://b.example/register-source">

o com'è qui usando window.open().

// With window.open()
window.open('...', '_blank', attributionsrc=${encodedUrl1}
  attributionsrc=${encodedUrl2})

In questi casi, entrambi gli URL ricevono navigation-source-eligible richieste attributionsrc (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, solo per le origini (non applicabile agli attivatori), puoi utilizzare un elenco di URL separati da spazi.

L'utilizzo degli 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.

Ciò è utile se vuoi effettuare la registrazione di origine rispondendo a una richiesta separata da quella principale dell'elemento.

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

Per il passaggio 1 della registrazione delle visualizzazioni, vai alle schede e seleziona il passaggio 1 Visualizzazioni.

Per registrare l'origine di attribuzione per una vista, puoi utilizzare un tag immagine o un tag 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=..."/>

Se vuoi, puoi specificare un valore URL per attributionsrc come faresti per i clic; ovvero, per un'immagine o uno script , puoi impostare l'URL attributionsrc o gli URL in questo modo:

Con un singolo URL:

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

Con un elenco di URL:

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

In uso: fetch() o XMLHttpRequest()

Questo codice simula in modo efficace l'effetto di una richiesta HTML con attributionsrc:

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

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

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

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

Per il passaggio 1 della registrazione dei clic, vai alle schede e seleziona Passaggio 1.

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

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

Esamina il codice di esempio per ulteriori informazioni.

Dopo aver ricevuto la richiesta del browser sul server, rispondi e includi nella tua 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 stringata, l'intestazione appare così:

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

Passaggi successivi

Scopri come registrare gli attivatori di attribuzione.