Registra gli attivatori di attribuzione

Scopri come registrare gli attivatori di attribuzione per conteggiare le conversioni.

Un attivatore di attribuzione è l'evento che indica al browser di acquisire le conversioni.

Seguendo la procedura descritta in questo documento, puoi registrare gli attivatori per registrare le conversioni che il browser attribuirà poi agli eventi di origine pertinenti, cioè le impressioni degli annunci o i clic sugli annunci.

Metodi di registrazione

Per registrare i trigger, utilizza elementi HTML o chiamate JavaScript:

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

In questo modo vengono generate richieste di rete a cui rispondi con un'intestazione di risposta HTTP della registrazione trigger.

Registra un attivatore per attribuire una conversione

La registrazione di un trigger è simile alla registrazione di un evento origine attribuzione. I passaggi completi sono descritti più avanti. Ecco il riepilogo:

1. Avvia la registrazione dell'attivatore. Utilizza un pixel o una chiamata fetch() per inviare una richiesta.

2. Completa la registrazione del trigger rispondendo con l'intestazione di registrazione del trigger.
   
   

   Dopo aver ricevuto la richiesta di pixel (inviata all'endpoint definito nel consueto attributo src o all'endpoint definito in attributionsrc se hai scelto di utilizzare attributionsrc e hai assegnato un valore), rispondi con l'intestazione Attribution-Reporting-Register-Trigger.
   
   

   In questa intestazione, specifica i dati di attivazione che vuoi che vengano visualizzati nei report. Questa intestazione può essere impostata da qualsiasi risposta. Se si tratta di una risposta a una richiesta effettuata da un sito che corrisponde a destination, le origini verranno abbinate. Quando l'intestazione viene ricevuta, il browser cerca le origini corrispondenti e pianifica un report.

   Esempio di report a livello di evento:

   {
     "event_trigger_data": [{
       "trigger_data": "[unsigned 64-bit integer]",
       "priority": "[signed 64-bit integer]",
       "deduplication_key": "[unsigned 64-bit integer]"
     }]
   }
   ```
   
   **Example for summary reports:**
   
   ```json
   {
     ... // existing fields, such as "event_trigger_data"
   
     "aggregatable_trigger_data": [
      {
        "key_piece": "0x400",
        "source_keys": ["campaignCounts"]
      },
      {
        "key_piece": "0xA80",
        "source_keys": ["geoValue", "nonMatchingKeyIdsAreIgnored"]
      }
     ],
     "aggregatable_values": {
       "campaignCounts": 32768,
       "geoValue": 1664
     }
   }
   ```
   

Nota: quando il browser riceve una risposta all'attivatore di attribuzione da un URL attributionsrc su una determinata pagina, viene effettuata una ricerca nello spazio di archiviazione locale per trovare un'origine che corrisponda sia all'origine attributionsrc sia al sito di destinazione a cui appartiene la pagina. Se vengono trovate più origini, il browser sceglie quella archiviata più di recente, a meno che le fonti non abbiano priorità diverse, in cui il browser sceglie quella con la priorità maggiore.

Gestire i sottodomini

Se destination è https://advertiser.example, è possibile attribuire le conversioni sia su https://advertiser.example sia sui relativi sottodomini, come https://shop.advertiser.example.

Se destination è https://shop.advertiser.example, è possibile attribuire le conversioni sia su https://advertiser.example che https://shop.advertiser.example.

Attributi obbligatori e facoltativi

Se utilizzi elementi HTML o effettui chiamate JavaScript per registrare i trigger, potresti dover utilizzare attributionsrc o attributionReporting. Per informazioni dettagliate su quando sono richiesti, consulta la tabella seguente.

Quando attributionsrc è facoltativo, il suo utilizzo indica che la richiesta è idonea per Attribution Reporting. 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	Trigger
Tag <a>	N/D Gli ancoraggi non possono registrare un trigger.
Tag <img>	attributionsrc è facoltativo. L'intestazione è sufficiente per registrare un trigger.
Tag <script>	attributionsrc è facoltativo. L'intestazione è sufficiente per registrare un trigger.
fetch chiamata	L'opzione attributionReporting è obbligatoria.
XMLHttpRequest	L'opzione attributionReporting è obbligatoria.
window.open()	N/D window.open non può registrare un trigger.

Passaggio 1: avvia la registrazione dell'attivatore

Puoi registrare un attivatore utilizzando un pixel (tag <img>) o un tag script.

Utilizzo di un pixel di conversione nuovo o esistente

Il seguente esempio attiva l'attribuzione su un'immagine esistente aggiungendo l'attributo attributionsrc.

L'origine di attributionsrc deve corrispondere all'origine che ha eseguito la registrazione dell'origine.

<img src="https://advertiser.example/conversionpixel"
     attributionsrc="https://adtech.example/attribution_trigger?purchase=13">

Il prossimo esempio attiva l'attribuzione aggiungendo un nuovo attributo del pixel di conversione attributionsrc.

L'origine di src deve corrispondere all'origine che ha eseguito la registrazione dell'origine.

<img src="https://adtech.example/conversionpixel"
     attributionsrc>

Punto chiave: in entrambi i casi, un'attribuzione può essere attivata solo su una pagina il cui sito corrisponde a quello fornito nella destinazione al momento della registrazione dell'origine.

Utilizzo di un tag script

Puoi eseguire la registrazione del trigger con un tag script; il comportamento è identico a <img>. I seguenti esempi di codice illustrano l'utilizzo di fetch() e XMLHttpRequest() (XHR).

Questo codice simula in modo efficace ciò che fa una richiesta HTML con attributionsrc:

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

// 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 XMLHttpRequest:
const attributionReporting = {
  eventSourceEligible: false,
  triggerEligible: true,
};

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

Punto chiave:

• L'origine o il valore url impostato in fetch() o open() deve corrispondere all'origine che ha eseguito la registrazione dell'origine.
• Un'attribuzione può essere attivata solo su una pagina il cui sito corrisponde a quello fornito nella destinazione al momento della registrazione dell'origine.

attributionsrc con o senza un valore

Puoi aggiungere attributionsrc con o senza un valore.

<!-- Without a value -->
<img src="..." width="1" height="1" attributionsrc>

<!--With a value (URL) -->
<img src="..." width="1" height="1" attributionsrc="https://...">

Se imposti un valore per attributionsrc, deve essere un singolo URL.

Se utilizzi un URL, il browser avvia una richiesta di recupero keepalive separata, una per ogni URL, che include l'intestazione della richiesta Attribution-Reporting-Eligible.

Questo è 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 per i clic su un elemento anchor, potresti non avere il controllo della destinazione; in questo caso, ti consigliamo una configurazione che invii l'intestazione della registrazione di origine in risposta a una richiesta separata dalla navigazione e che puoi controllare completamente. Se specifica un valore esplicito per attributionsrc, indichi al browser di effettuare questa richiesta aggiuntiva e di configurare la sua destinazione.

Passaggio 2: rispondi con un'intestazione

Dopo aver ricevuto la richiesta del browser, rispondi e includi nella risposta l'intestazione Attribution-Reporting-Register-Trigger:

JSON.stringify({event_trigger_data: [{
      trigger_data: '412444888111012',
      // Optional
      priority: '1000000000000',
      deduplication_key: '2345698765'
    }], debug_key: '1115698977'})

Attenzione:il valore del campo event_trigger_data deve essere nidificato tra parentesi quadre, perché il browser prevede un array JSON. Questo è utile per i filtri.

Passaggi successivi

Scopri come registrare le origini di attribuzione.