Questa pagina è stata tradotta dall'API Cloud Translation.

Configurare i report di debug per Attribution Reporting

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)

di Gemini Advanced.

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

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.

Codice demo: debug biscotto

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

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.

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

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.

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

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 tipo trigger-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

A seguire

Parte 3: debug del libro di ricette