Configurare i report di debug per Attribution Reporting

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
  }
}]

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

Passaggio 1: imposta il cookie di debug

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.

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

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