Configurare i report di debug per Attribution Reporting

Parte 2 di 3 sul debug di Attribution Reporting. Configura i report di debug.

Nota: questo articolo fa parte di una serie sul debug dell'API Attribution Reporting. Questa serie tratta il debug lato client per i report a livello di evento e i report aggregabili. Le indicazioni sul debug lato server per i report di riepilogo sono disponibili su GitHub.

Glossario

• L'origine dei report è l'origine che [imposta le intestazioni origine e trigger di Attribution Reporting. Tutti i report generati dal browser vengono inviati a questa origine. In queste istruzioni, utilizziamo https://adtech.example come origine del rapporto di esempio.
• Un report sull'attribuzione (report in breve) è il report finale (a livello di evento o aggregabile) che contiene i dati di misurazione richiesti.
• Un report di debug contiene dati aggiuntivi su un report sull'attribuzione o su un'origine o un evento attivatore. La ricezione di un report di debug non significa necessariamente che qualcosa non funzioni correttamente. Esistono due tipi di report di debug
• Un report di debug di transizione è un report di debug che richiede l'impostazione di un cookie per poter essere generato e inviato. I report di debug di transizione non saranno disponibili se non viene impostato un cookie e una volta che i cookie di terze parti verranno ritirati. Tutti i report di debug descritti in questa guida sono report di debug di transizione.
• I report di debug riusciti monitorano la generazione riuscita di un report sull'attribuzione. Sono direttamente correlate a un report sull'attribuzione. I report di debug riusciti sono disponibili a partire da Chrome 101 (aprile 2022).
• I report di debug dettagliati possono monitorare i report mancanti e aiutarti a determinarne il motivo. Indicano i casi in cui il browser non ha registrato un'origine o un evento di attivazione (il che significa che non genererà un report sull'attribuzione) e i casi in cui un report sull'attribuzione non può essere generato o inviato per qualche motivo. I report di debug dettagliati includono un campo type che descrive il motivo per cui non è stato generato un evento di origine, un evento di trigger o un report sull'attribuzione. I report di debug dettagliati sono disponibili a partire da Chrome 109 (stabile a gennaio 2023).
• Le chiavi di debug sono identificatori univoci che puoi impostare sia sul lato origine sia sul lato attivatore. Le chiavi di debug consentono di mappare le conversioni basate sui cookie e le conversioni basate sull'attribuzione. Dopo aver configurato il sistema per generare report di debug e impostare le chiavi di debug, il browser includerà queste chiavi in tutti i report sull'attribuzione e in tutti i report di debug.

Per ulteriori concetti e termini chiave utilizzati nella nostra documentazione, consulta il glossario di Privacy Sandbox.

Domande sull'implementazione?

Se riscontri problemi durante la configurazione dei report di debug, crea un problema nel nostro repository di assistenza per gli sviluppatori e ti aiuteremo a risolverlo.

Prepararsi a configurare i report di debug

Prima di impostare i report di debug:

Verificare di aver applicato le best practice per l'integrazione dell'API

• Verifica che il codice sia limitato al rilevamento delle funzionalità. Per assicurarti che l'API non sia bloccata da Permissions-Policy, esegui questo codice:

  if (document.featurePolicy.allowsFeature('attribution-reporting')) {
  // the Attribution Reporting API is enabled
  }
  

  Se questo controllo di rilevamento delle funzionalità restituisce true, l'API è consentita nel contesto (pagina) in cui viene eseguito il controllo.

• (Non richiesto durante la fase di test: controlla di aver impostato un criterio di autorizzazione)

Punto chiave: i requisiti relativi alle autorizzazioni e alle norme sono stati rilassati per i test, ma un publisher o un inserzionista può comunque decidere di disattivare esplicitamente l'API Attribution Reporting utilizzando le norme sulle autorizzazioni. In questo caso, non è possibile registrare alcuna origine o attivatore (di conseguenza non è possibile generare o inviare report).

Risolvere i problemi di integrazione fondamentali

Sebbene i report di debug siano utili per rilevare e analizzare le perdite su larga scala, alcuni problemi di integrazione possono essere rilevati localmente. I problemi di configurazione errata dell'intestazione dell'origine e dell'attivatore, i problemi di analisi JSON, il contesto non sicuro (non HTTPS) e altri problemi che impediscono il funzionamento dell'API verranno visualizzati nella scheda Problemi di DevTools.

Nota: questi problemi non generano report di debug dettagliati, perché causano il malfunzionamento dell'API. Solo l'assenza di report di debug riusciti indica che potresti riscontrare alcuni di questi problemi. Scopri di più nella Parte 3: Libro di ricette sul debug.

I problemi di DevTools possono essere di diversi tipi. Se si verifica un problema relativo a invalid header, copia l'intestazione nello strumento di convalida delle intestazioni. In questo modo potrai identificare e risolvere più facilmente il campo che causa un problema.

Configurare i report di debug: passaggi comuni per i report di operazione riuscita e i report dettagliati

Passaggio 1: imposta il cookie di debug

Imposta il seguente cookie sull'origine report:

Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly

Il browser verificherà la presenza di questo cookie sia nella registrazione dell'origine che dell'attivatore. Il report di debug riuscito viene generato solo se il cookie è presente in entrambi i momenti.

Codice demo: cookie di debug

Tieni presente che i report di debug possono essere attivati per i browser in modalità B, dove i cookie di terze parti vengono disattivati per facilitare i test e la preparazione al ritiro dei cookie di terze parti. Per i browser in modalità B, non è necessario impostare il cookie di debug per attivare i report di debug. Vai al passaggio 2 per configurare le chiavi di debug per i report di debug riusciti.

Passaggio 2: imposta le chiavi di debug

Ogni chiave di debug deve essere un numero intero senza segno a 64 bit formattato come stringa Base10. Imposta ogni chiave di debug come ID univoco. Il report di debug riuscito viene generato solo se sono impostate le chiavi di debug.

• Mappa la chiave di debug lato origine a informazioni aggiuntive relative alla data/ora che ritieni siano pertinenti per il debug.
• Mappa la chiave di debug lato trigger a informazioni aggiuntive sul tempo di attivazione che ritieni pertinenti per il debug.

Ad esempio, puoi impostare le seguenti chiavi di debug:

• ID cookie + timestamp di origine come chiave di debug dell'origine (e acquisire lo stesso timestamp nel tuo sistema basato sui cookie)
• ID cookie + timestamp di trigger come chiave di debug dell'attivatore (e acquisire lo stesso timestamp nel tuo sistema basato sui cookie)

In questo modo, puoi utilizzare le informazioni sulle conversioni basate sui cookie per cercare i report di debug o i report sull'attribuzione corrispondenti. Scopri di più nella Parte 3: Libro di ricette.

Rendi la chiave di debug lato origine diversa da source_event_id, in modo da poter differenziare i singoli report che hanno lo stesso ID evento di origine.

Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"647775351539539"
}

Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743"
}

Codice demo: chiave di debug sorgente Codice demo: chiave di debug attiva

Nota: nel codice demo, forniamo a entrambe le chiavi di debug il valore del cookie di terze parti di misurazione precedente. In un sistema reale, dovresti impostare ogni chiave come ID univoco e mapparla alle informazioni aggiuntive relative all'ora della fonte che ritieni utili per il debug, come suggerito nelle chiavi di debug di esempio riportate sopra.

Configurare i report di debug con esito positivo

Nota: prova la demo per generare e visualizzare in anteprima i report di debug riusciti nel tuo browser. Esamina il codice corrispondente.

Il codice di esempio in questa sezione genera report di debug efficaci per entrambi i report aggregabili a livello di evento. I report aggregabili a livello di evento usano le stesse chiavi di debug.

Passaggio 3: configura un endpoint per raccogliere report di debug con esito positivo

Configura un endpoint per raccogliere i report di debug. Questo endpoint dovrebbe essere simile all'endpoint di attribuzione principale, con un'ulteriore stringa debug nel percorso:

• Endpoint per i report di debug riusciti a livello di evento: https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
  • Endpoint per i report di debug riusciti aggregabili: https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution

Quando viene attivata un'attribuzione, il browser invia immediatamente un report di debug tramite una richiesta POST a questo endpoint. Il codice server per gestire i report di debug di esito positivo in arrivo potrebbe avere il seguente aspetto (qui su un endpoint del nodo):

// Handle incoming event-Level Success Debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/report-event-attribution',
  async (req, res) => {
    // Debug report is in req.body
    res.sendStatus(200);
  }
);

// Handle incoming aggregatable Success Debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/report-aggregate-attribution',
  async (req, res) => {
    // Debug report is in req.body
    res.sendStatus(200);
  }
);

Codice demo: endpoint dei report di debug a livello di evento

Codice demo: endpoint dei report di debug aggregabili

Passaggio 4: verifica che la configurazione generi report di debug riusciti

• Apri chrome://attribution-internals nel browser.
• Assicurati che la casella di controllo Mostra report di debug sia selezionata nelle schede Report a livello di evento e Report aggregati.
• Apri i siti su cui hai implementato i report sull'attribuzione. Completa i passaggi utilizzati per generare i report sull'attribuzione; questi stessi passaggi genereranno report di debug corretti.
• Tra chrome://attribution-internals:
  • Verifica che i report sull'attribuzione siano generati correttamente.
  • Nelle schede Report a livello di evento e Report aggregati, verifica che vengano generati anche i report di debug corretti. Riconoscerli nell'elenco con il percorso debug blu.

• Sul server, verifica che l'endpoint riceva immediatamente questi report di debug riuscito. Assicurati di controllare se sono presenti report di debug validi a livello di evento e aggregabili.

Passaggio 5: osserva i report di debug riusciti

Un report di debug riuscito è identico a un report sull'attribuzione e contiene le chiavi di debug lato origine e lato trigger.

{
  "attribution_destination": "https://advertiser.example",
  "randomized_trigger_rate": 0.0000025,
  "report_id": "7d76ef29-d59e-4954-9fff-d97a743b4715",
  "source_debug_key": "647775351539539",
  "source_event_id": "760938763735530",
  "source_type": "event",
  "trigger_data": "0",
  "trigger_debug_key": "156477391437535"
}

{
  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgqJldmFsdWVEAACAAGZidWNrZXRQPPhnkD+7c+wm1RjAlowp3KJldmFsdWVEAAARMGZidWNrZXRQJFJl9DLxbnMm1RjAlowp3GlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "d5f32b96-abd5-4ee5-ae23-26490d834012",
      "payload": "0s9mYVIuznK4WRV/t7uHKquHPYCpAN9mZHsUGNiYd2G/9cg87Y0IjlmZkEtiJghMT7rmg3GtWVPWTJU5MvtScK3HK3qR2W8CVDmKRAhqqlz1kPZfdGUB4NsXGyVCy2UWapklE/r7pmRDDP48b4sQTyDMFExQGUTE56M/8WFVQ0qkc7UMoLI/uwh2KeIweQCEKTzw"
    }
  ],
  "shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://advertiser.example\",\"debug_mode\":\"enabled\",\"report_id\":\"4a04f0ff-91e7-4ef6-9fcc-07d000c20495\",\"reporting_origin\":\"https://adtech.example\",\"scheduled_report_time\":\"1669888617\",\"source_registration_time\":\"1669852800\",\"version\":\"0.1\"}",
  "source_debug_key": "647775351539539",
  "trigger_debug_key": "156477391437535"
}

Configurare report di debug dettagliati

Nota: prova la demo per generare e visualizzare in anteprima report di debug dettagliati nel tuo browser. Esamina il codice corrispondente.

Passaggio 3: attiva il debug dettagliato nelle intestazioni dell'origine e dell'attivatore

Imposta debug_reporting su true sia in Attribution-Reporting-Register-Source che in Attribution-Reporting-Register-Trigger.

Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}

Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}

Codice demo: intestazione source

Codice demo: intestazione attivatore

Passaggio 4: configura un endpoint per raccogliere report di debug dettagliati

Configura un endpoint per raccogliere i report di debug. Questo endpoint dovrebbe essere simile all'endpoint di attribuzione principale, con una stringa debug/verbose aggiuntiva nel percorso:

https://adtech.example/.well-known/attribution-reporting/debug/verbose

Quando vengono generati report di debug dettagliati, ovvero quando un'origine o un trigger non sono registrati, il browser invia immediatamente un report di debug dettagliato tramite una richiesta POST a questo endpoint. Il codice del tuo server per gestire i report di debug dettagliati in arrivo potrebbe avere il seguente aspetto (qui su un endpoint del nodo):

// Handle incoming verbose debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/verbose',
  async (req, res) => {
    // List of verbose debug reports is in req.body
    res.sendStatus(200);
  }
);

A differenza dei report di debug riusciti, per i report dettagliati esiste un solo endpoint. I report dettagliati relativi a report aggregati e a livello di evento verranno inviati tutti allo stesso endpoint.

Codice demo: endpoint per report di debug dettagliati

Passaggio 5: verifica che la configurazione generi report di debug dettagliati

Anche se esistono molti tipi di report di debug dettagliati, è sufficiente controllare la configurazione del debug dettagliato con un solo tipo di report di debug dettagliato. Se questo tipo di report di debug dettagliato viene generato e ricevuto correttamente, significa che verranno generati e ricevuti correttamente anche tutti i tipi di report di debug dettagliati, poiché tutti i report di debug dettagliati utilizzano la stessa configurazione e vengono inviati allo stesso endpoint.

Punto chiave: scegli un report di debug dettagliato che sia semplice da testare. trigger-no-matching-source è un buon candidato, perché puoi generarlo convertendo. I report dettagliati relativi agli eventi di attivazione tendono a essere candidati migliori; i tipi di report dettagliati che riguardano gli eventi di origine sono più noiosi da generare intenzionalmente.

1. Apri chrome://attribution-internals nel browser.
2. Attivare un'attribuzione (conversione) sul tuo sito configurata con i report sull'attribuzione. Dato che non si è verificata alcuna interazione con l'annuncio (impressione o clic) prima di questa conversione, verrà generato un report di debug dettagliato di tipo trigger-no-matching-source.
3. In chrome://attribution-internals, apri la scheda Report di debug dettagliati e verifica che sia stato generato un report di debug dettagliato di tipo trigger-no-matching-source.
4. Sul server, verifica che l'endpoint abbia ricevuto immediatamente questo report di debug dettagliato.

Passaggio 6: osserva i report di debug dettagliati

I report di debug dettagliati generati al momento del trigger includono sia la chiave di debug lato origine sia la chiave di debug lato trigger (se esiste un'origine corrispondente per il trigger). I report di debug dettagliati generati al momento dell'origine includono la chiave di debug lato origine.

Esempio di richiesta contenente report di debug dettagliati, inviati dal browser:

[
  {
    "body": {
      "attribution_destination": "http://arapi-advertiser.localhost",
      "randomized_trigger_rate": 0.0000025,
      "report_id": "92b7f4fd-b157-4925-999e-aad6361de759",
      "source_debug_key": "282273499788483",
      "source_event_id": "480041649210491",
      "source_type": "event",
      "trigger_data": "1",
      "trigger_debug_key": "282273499788483"
    },
    "type": "trigger-event-low-priority"
  },
  {
    "body": {
      "attribution_destination": "http://arapi-advertiser.localhost",
      "limit": "65536",
      "source_debug_key": "282273499788483",
      "source_event_id": "480041649210491",
      "source_site": "http://arapi-publisher.localhost",
      "trigger_debug_key": "282273499788483"
    },
    "type": "trigger-aggregate-insufficient-budget"
  }
]

Punto chiave: a differenza di una richiesta di debug dettagliata, una richiesta di debug dettagliata contiene un elenco (array) di report dettagliati nel corpo.

Ogni report dettagliato contiene i seguenti campi:

Type

Che cosa ha causato la generazione del report. Per scoprire di più su tutti i tipi di report dettagliati e su quale azione intraprendere in base a ciascun tipo, consulta il riferimento ai report dettagliati nella Parte 3: Debug del libro di cucina.

Body

Corpo del report. Dipende dal tipo. Consulta il riferimento ai report dettagliati nella Parte 3: debug del libro di cucina.

Il corpo di una richiesta conterrà almeno uno e al massimo due report dettagliati:

• Un report dettagliato se l'errore riguarda solo i report a livello di evento (o se interessa solo i report aggregabili). Un'origine o un errore di registrazione dell'attivatore ha un solo motivo, perciò è possibile generare un report dettagliato per errore e per tipo di report (aggregabile a livello di evento).
• Due report dettagliati se il fallimento interessa sia i report aggregabili a livello di evento, con un'eccezione: se il motivo dell'errore è lo stesso per i report aggregabili a livello di evento, viene generato un solo report dettagliato (esempio: trigger-no-matching-source)

A seguire

Parte 3: ricettari sul debug