Configurare i report di debug per Attribution Reporting

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

Glossario

  • The reporting origin is the origin that sets the Attribution Reporting source and trigger headers. All reports generated by the browser are sent to this origin. In this guidance, we use https://adtech.example as the example reporting origin.
  • An attribution report (report for short) is the final report (event-level or aggregatable) that contains the measurement data you've requested.
  • A debug report contains additional data about an attribution report, or about a source or trigger event. Receiving a debug report does not necessarily mean that something is working incorrectly! There are two types of debug reports
  • A transitional debug report is a debug report that requires a cookie to be set in order to be generated and sent. Transitional debug reports will be unavailable if a cookie is not set, and once third-party cookies are deprecated. All debug reports described in this guide are transitional debug reports.
  • Success debug reports track successful generation of an attribution report. They relate directly to an attribution report. Success debug reports have been available since Chrome 101 (April 2022).
  • Verbose debug reports can track missing reports and help you determine why they're missing. They indicate cases where the browser did not record a source or trigger event, (which means it will not generate an attribution report), and cases where an attribution report can't be generated or sent for some reason. Verbose debug reports include a type field that describes the reason why a source event, trigger event or attribution report was not generated. Verbose debug reports are available starting in Chrome 109 (Stable in January 2023).
  • Debug keys are unique identifiers you can set on both the source side and the trigger side. Debug keys enable you to map cookie-based conversions and attribution-based conversions. When you've set up your system to generate debug reports and set debug keys, the browser will include these debug keys in all attribution reports and debug reports.

For more concepts and key terms used throughout our documentation, refer to the Privacy Sandbox glossary.

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 configurare i report di debug, segui questi passaggi:

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

  • Verifica che il codice sia protetto dal rilevamento delle funzionalità. Per assicurarti che l'API non sia bloccata da Permissions-Policy, esegui il seguente 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 obbligatorio durante la fase di test: verifica di aver impostato un'Permissions-Policy)

Risolvere i problemi di integrazione fondamentali

Sebbene i report di debug siano utili per rilevare e analizzare la perdita su larga scala, alcuni problemi di integrazione possono essere rilevati localmente. I problemi di configurazione errata dell'intestazione di origine e trigger, 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.

I problemi di DevTools possono essere di diversi tipi. Se riscontri un problema invalid header, copia l'intestazione nello strumento di convalida delle intestazioni. In questo modo potrai identificare e correggere il campo che causa un problema.

Convalida delle intestazioni di Attribution Reporting

Puoi utilizzare lo strumento di convalida delle intestazioni per convalidare le intestazioni correlate all'API Attribution Reporting. Puoi monitorare gli errori di convalida provenienti dal browser per facilitare il debug dell'API.

Per attivare la ricezione dei report di debug, rispondi con report-header-errors nell'intestazione della risposta Attribution-Reporting-Info.

Attribution-Reporting-Info: report-header-errors

Tieni presente che Attribution-Reporting-Info è un header strutturato a dizionarioAttribution-Reporting-Info, quindi fornire la chiave booleana report-header-errors implica un valore true.

I report di debug vengono inviati immediatamente all'endpoint di reporting:

https://<reporting origin>/.well-known/attribution-reporting/debug/verbose

I dati del report sono inclusi nel corpo della richiesta come elenco JSON di oggetti con questo formato:

[{
  "type": "header-parsing-error",
  "body": {
    "context_site": "https://source.example",
    "header": "Attribution-Reporting-Register-Source",
    "value": "!!!", // header value received in the response
    "error": "invalid JSON" // optional error details that may vary across browsers or different versions of the same browser
  }
}]
Strumento di convalida delle intestazioni
Strumento di convalida dell'intestazione

Configurare i report di debug: passaggi comuni ai report di successo e dettagliati

Imposta il seguente cookie sull'origine dei report:

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

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

Codice demo: debug cookie

Tieni presente che i report di debug possono essere attivati per i browser in modalità B, in cui i cookie di terze parti sono 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 in base 10. Rendi ogni chiave di debug un ID univoco. Il report di debug di esito positivo verrà generato solo se sono impostate le chiavi di debug.

  • Mappa la chiave di debug lato origine a ulteriori informazioni sull'origine che ritieni pertinenti per il debug.
  • Mappa la chiave di debug lato trigger con informazioni aggiuntive relative al momento del trigger 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 acquisisci lo stesso timestamp nel tuo sistema basato sui cookie)
  • ID cookie + Timestamp trigger come chiave di debug del trigger (e acquisisci 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 di attribuzione corrispondenti. Scopri di più nella Parte 3: Cookbook.

Rendi la chiave di debug lato origine diversa da source_event_id, in modo da poter distinguere 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"
}

Demo code: source debug key Demo code: trigger debug key

Configurare i report di debug degli esiti positivi

Il codice di esempio in questa sezione genera report di debug riusciti sia per i report a livello di evento sia per quelli aggregabili. I report a livello di evento e aggregabili utilizzano le stesse chiavi di debug.

Passaggio 3: configura un endpoint per raccogliere i report di debug degli errori

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

  • Endpoint per i report di debug di successo 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 utilizzando una richiesta POST a questo endpoint. Il codice del server per gestire i report di debug di esito positivo in entrata 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 per 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 sia nelle schede Report a livello di evento che in quelle Report aggregabili.
  • Apri i siti su cui hai implementato Attribution Reporting. Completa i passaggi che utilizzi per generare i report sull'attribuzione. Questi stessi passaggi genereranno report di debug riusciti.
  • In chrome://attribution-internals:
    • Verifica che i report sull'attribuzione vengano generati correttamente.
    • Nelle schede Report a livello di evento e Report aggregabili, controlla che vengano generati anche i report di debug riusciti. Riconoscili nell'elenco con il percorso blu debug.
Elementi interni dell&#39;attribuzione
Elementi interni dell'attribuzione
  • Sul server, verifica che l'endpoint riceva immediatamente questi report di debug di esito positivo. Assicurati di controllare i report di debug riusciti sia a livello di evento sia aggregabili.
Log del server di origine dei report
Reporting origin server logs

Passaggio 5: osserva i report di debug riusciti

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

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

Passaggio 3: attiva il debug dettagliato nelle intestazioni di origine e trigger

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 sorgente

Codice demo: trigger intestazione

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

Configura un endpoint per raccogliere i report di debug. Questo endpoint deve 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 una sorgente o un attivatore non è registrato, il browser invia immediatamente un report di debug dettagliato utilizzando una richiesta POST a questo endpoint. Il codice del server per gestire i report di debug dettagliati in entrata potrebbe avere il seguente aspetto (qui su un endpoint 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, esiste un solo endpoint per i report dettagliati. I report dettagliati relativi ai report a livello di evento e aggregati verranno tutti inviati allo stesso endpoint.

Codice demo: endpoint report di debug dettagliati

Passaggio 5: conferma che la configurazione genererà report di debug dettagliati

Sebbene esistano numerosi tipi di report di debug dettagliato, è 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 anche tutti gli altri tipi di report di debug dettagliato verranno generati e ricevuti correttamente, perché tutti utilizzano la stessa configurazione e vengono inviati allo stesso endpoint.

  1. Apri chrome://attribution-internals nel browser.
  2. Attiva un'attribuzione (conversione) sul tuo sito configurato con Attribution Reporting. Poiché non si è verificato alcun coinvolgimento 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 dell'attivazione includono sia la chiave di debug lato sorgente sia quella lato attivazione (se esiste una sorgente corrispondente per l'attivazione). I report di debug dettagliati generati al momento dell'origine includono la chiave di debug lato origine.

Esempio di una richiesta contenente report di debug dettagliati, inviata 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"
  }
]

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 a seconda del tipo, consulta il riferimento ai report dettagliati nella Parte 3: Debug cookbook.
Body
Il corpo del report. Dipende dal tipo. Consulta il riferimento ai report dettagliati nella Parte 3: Debug cookbook.

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

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

A seguire

Parte 3: Ricettario per il debug