Parte 2 di 3 sul debug dei report sull'attribuzione. Configura i report di debug.
Glossario
- L'origine dei report è l'origine che imposta l'origine e l'attivatore di Attribution Reporting.
Tutti i report generati dal browser vengono inviati a questa origine. In queste indicazioni,
utilizziamo
https://adtech.example
come origine di segnalazione di esempio. - Un report sull'attribuzione (in breve report) è il report finale (a livello di evento o aggregabile) contenente i dati di misurazione che hai richiesto.
- Un report di debug contiene dati aggiuntivi su un report sull'attribuzione o su un'origine o un evento di attivazione. La ricezione di un report di debug non significa necessariamente che qualcosa funzioni in modo errato. 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 quando 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. Sono disponibili report di debug riuscito a partire dalla versione 101 di Chrome (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 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 un evento di origine, un evento di attivazione o un report sull'attribuzione non è stato generato. 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 di origine sia sul lato trigger. Le chiavi di debug ti consentono di mappare le conversioni basate sui cookie e quelle basate sull'attribuzione. Una volta configurato il sistema per generare report di debug e impostare chiavi di debug, il browser includerà queste chiavi di debug in tutti i report sull'attribuzione e in tutti i report di debug.
Per altri concetti e termini chiave utilizzati nella nostra documentazione, consulta il glossario di Privacy Sandbox.
Hai domande sull'implementazione?
Se riscontri problemi durante la configurazione dei report di debug, crea un problema su la nostra assistenza per gli sviluppatori di archiviazione e ti aiuteremo a risolvere il problema.
Prepararsi a impostare i report di debug
Prima di impostare i report di debug, segui questi passaggi:
Verificare di aver applicato le best practice per l'integrazione delle API
Verifica che il codice sia protetto da rilevamento delle funzionalità. per assicurarti che l'API non è bloccato daPermissions-Policy, esegui questo codice:
if (document.featurePolicy.allowsFeature('attribution-reporting')) { // the Attribution Reporting API is enabled }
Se questo controllo di rilevamento della funzionalità restituisce true, l'API è consentita nella 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 le perdite su larga scala, alcuni problemi di integrazione possono essere rilevati a livello locale. Intestazione e intestazione trigger problemi di configurazione errata, problemi di analisi JSON, contesto non sicuro (non HTTPS) e emergono altri problemi che impediscono il funzionamento dell'API Scheda Problemi di DevTools.
I problemi di DevTools possono essere di tipo diverso. Se riscontri un invalid header
risolvere il problema, copia l'intestazione nello strumento di convalida intestazioni
strumento di authoring. Questo
ti aiuterà a identificare e correggere il campo che causa un problema.
![Screenshot: strumento di convalida delle intestazioni](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/screenshot-header-valida-6fe8347784caf.png?authuser=19&hl=it)
Imposta i report di debug: passaggi comuni per i report di esito positivo e i report dettagliati
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 sull'origine che sull'origine attivare la registrazione. Il report di debug riuscito verrà generato solo se in entrambi i casi.
Tieni presente che i report di debug possono essere attivati per i browser in Modalità B, dove i cookie di terze parti sono disabilitati per facilitare i test e la preparazione 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 ottenere 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 base-10. Rendi ogni chiave di debug un ID univoco. Il report di debug riuscito verrà generato solo se sono impostate le chiavi di debug.
- Mappa la chiave di debug lato origine a informazioni aggiuntive sull'ora di origine pertinente per il debug.
- Mappa la chiave di debug lato trigger a informazioni aggiuntive sul tempo di attivazione pertinente per il debug.
Ad esempio, puoi impostare le seguenti chiavi di debug:
- ID cookie + timestamp di origine come chiave di debug della sorgente (e acquisisci lo stesso nel tuo sistema basato sui cookie)
- ID cookie + timestamp del trigger come chiave di debug dell'attivatore (e acquisisci lo stesso nel tuo sistema basato sui cookie)
Con questo, 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: debug sorgente Codice demo: trigger debug
Configura report di debug riusciti
Il codice di esempio in questa sezione genera report di debug riusciti per entrambi e aggregabili a livello di evento. I report aggregabili a livello di evento utilizzano le stesse chiavi di debug.
Passaggio 3: configura un endpoint per raccogliere i report di debug riusciti
Configura un endpoint per raccogliere i report di debug. Questo endpoint dovrebbe essere simile
all'endpoint di attribuzione principale, con una stringa debug
aggiuntiva nel percorso:
- Endpoint per report di debug sulle operazioni riuscite a livello di evento:
https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
- Endpoint per report di debug eseguiti con aggregatable:
https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution
- Endpoint per report di debug eseguiti con aggregatable:
Quando viene attivata un'attribuzione, il browser invia immediatamente un debug
segnala tramite una richiesta POST
a questo endpoint. Il codice del server da gestire
i report di debug in arrivo potrebbero avere il seguente aspetto (qui su un endpoint 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 dimostrativo: report di debug a livello di evento endpoint
Codice dimostrativo: report di debug aggregabili endpoint
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 Report a livello di evento e Report aggregati.
- Apri i siti su cui hai implementato Attribution Reporting. Completata i passaggi utilizzati per generare i report sull'attribuzione; gli stessi passaggi e generare report di debug riusciti.
- 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 eseguiti con successo. Riconoscili
nell'elenco con il relativo percorso
debug
blu.
![Screenshot: Interni dell'attribuzione](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/screenshot-attribution-i-e7d3e5d9e396.png?authuser=19&hl=it)
- Sul server, verifica che l'endpoint riceva immediatamente queste operazioni riuscite report di debug. Assicurati di controllare sia l'aggregazione a livello di evento report di debug eseguiti con successo.
![Screenshot: log del server di origine report](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/screenshot-reporting-ori-89d44854473d7.png?authuser=19&hl=it)
Passaggio 5: osserva i report di debug eseguiti con successo
Un report di debug riuscito è identico a un report sull'attribuzione e contiene entrambi 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
Passaggio 3: attiva il debug dettagliato nelle intestazioni di origine e attiva
Imposta debug_reporting
su true
in Attribution-Reporting-Register-Source
e 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: sorgente intestazione
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 dovrebbe essere simile
all'endpoint di attribuzione principale, con una stringa debug/verbose
aggiuntiva in
il percorso:
https://adtech.example/.well-known/attribution-reporting/debug/verbose
Quando vengono generati report di debug dettagliati, ovvero quando un'origine o un trigger
registrato, il browser invierà immediatamente un report di debug dettagliato tramite un
POST
richiesta a questo endpoint. Il codice del tuo server per gestire il traffico dettagliato in arrivo
i report di debug possono 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, esiste un solo endpoint per i report dettagliati. I report dettagliati relativi ai report aggregati e a livello di evento saranno tutti inviati allo stesso endpoint.
Codice dimostrativo: report di debug dettagliati endpoint
Passaggio 5: verifica che la configurazione generi report di debug dettagliati
Esistono numerosi tipi di report di debug dettagliato, ma è sufficiente Controllare la configurazione del debug dettagliato con un solo tipo di debug dettagliato. report. Se questo tipo di report di debug dettagliato viene generato correttamente ciò significa che tutti i tipi di report di debug dettagliati verranno generati e ricevuti, dato che tutti i rapporti di debug dettagliati utilizzano lo stesso configurazione e vengono inviati allo stesso endpoint.
- Apri
chrome://attribution-internals
nel browser. - Attivare un'attribuzione (conversione) sul tuo sito configurata con l'attribuzione
Generazione di report. Dato che non c'è stato alcun coinvolgimento con l'annuncio (impressioni o clic)
prima di questa conversione, dovresti aspettarti un report di debug dettagliato di tipo
Verrà generato
trigger-no-matching-source
. - In
chrome://attribution-internals
, apri la scheda Report di debug dettagliati e verifica che un report di debug dettagliato di tipotrigger-no-matching-source
è stato generato. - Sul tuo 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 il lato di origine che 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 il debug lato origine chiave.
Esempio di una 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"
}
]
Ogni report dettagliato contiene i seguenti campi:
Type
- Che cosa ha generato la generazione del report. Per saperne di più su tutte le tipi di rapporti e quali azioni intraprendere in base a ciascun tipo, esamina le Riferimento ai report dettagliati nella Parte 3: debug libro di ricette.
Body
- Il corpo del report. Dipende dal tipo. Rivedi le informazioni dettagliate riferimento ai report nella Parte 3: debug libro di ricette.
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 influisce solo sui report aggregabili). Un errore di registrazione dell'origine o del trigger ha un solo motivo: pertanto è possibile generare un report dettagliato per ogni errore e per tipo di report (a livello di evento o aggregabile).
- Due report dettagliati se l'errore riguarda sia a livello di evento che aggregabili
report, con un'eccezione: se il motivo dell'errore è lo stesso per gli eventi a livello di evento
e aggregabili, viene generato un solo report dettagliato (ad esempio:
trigger-no-matching-source