Teil 2 von 3 zur Fehlerbehebung in Attribution Reporting. Debug-Berichte einrichten
Glossar
- Die Quelle der Berichterstellung ist die Quelle, über die die Header Quelle und Trigger von Attribution Reporting festgelegt werden.
Alle vom Browser erstellten Berichte werden an diesen Ursprung gesendet. In dieser Anleitung verwenden wir
https://adtech.example
als Beispielquelle für die Berichterstellung. - Ein Attributionsbericht (kurz Bericht) ist der Abschlussbericht (auf Ereignisebene oder aggregierbar), der die angeforderten Messdaten enthält.
- Ein Debug-Bericht enthält zusätzliche Daten zu einem Attributionsbericht oder zu einer Quelle oder einem Triggerereignis. Wenn Sie einen Debug-Bericht erhalten, bedeutet das nicht unbedingt, dass ein Fehler vorliegt. Es gibt zwei Arten von Fehlerbehebungsberichten.
- Ein Debug-Bericht vom Typ „Transitional“ ist ein Debugging-Bericht, für den ein Cookie festgelegt werden muss, damit er generiert und gesendet wird. Berichte zur vorübergehenden Fehlerbehebung sind nicht mehr verfügbar, wenn kein Cookie gesetzt wird oder Drittanbieter-Cookies nicht mehr unterstützt werden. Alle in diesem Leitfaden beschriebenen Fehlerbehebungsberichte sind Übergangsberichte.
- In Berichten zur Fehlerbehebung wird die erfolgreiche Erstellung eines Attributionsberichts erfasst. Sie beziehen sich direkt auf einen Attributionsbericht. Berichte zur Fehlerbehebung sind seit Chrome 101 (April 2022) verfügbar.
- Mit ausführlichen Debugging-Berichten können Sie fehlende Berichte verfolgen und herausfinden, warum sie fehlen. Sie weisen auf Fälle hin, in denen der Browser keine Quelle oder kein Trigger-Ereignis aufgezeichnet hat und somit keinen Attributionsbericht generiert. Außerdem werden Fälle angezeigt, in denen aus irgendeinem Grund kein Attributionsbericht generiert oder gesendet werden kann.
Ausführliche Fehlerbehebungsberichte enthalten ein
type
-Feld, das den Grund beschreibt, warum kein Quellereignis, Triggerereignis oder Attributionsbericht generiert wurde. Berichte zur ausführlichen Fehlerbehebung sind ab Chrome 109 verfügbar (stabil im Januar 2023). - Fehlerbehebungsschlüssel sind eindeutige Kennungen, die Sie sowohl auf der Quell- als auch auf der Trigger-Seite festlegen können. Mit Schlüsseln zur Fehlerbehebung können Sie auf Cookies und Attribution basierende Conversions zuordnen. Wenn Sie Ihr System so eingerichtet haben, dass Fehlerbehebungsberichte generiert und Fehlerbehebungsschlüssel festgelegt werden, nimmt der Browser diese Fehlerbehebungsschlüssel in alle Attributions- und Fehlerbehebungsberichte auf.
Weitere Konzepte und Schlüsselbegriffe, die in unserer Dokumentation verwendet werden, finden Sie im Privacy Sandbox-Glossar.
Haben Sie Fragen zur Implementierung?
Wenn beim Einrichten von Fehlerbehebungsberichten ein Problem auftritt, erstellen Sie ein Problem in unserem Entwickler-Support-Repository. Wir helfen Ihnen dann bei der Fehlerbehebung.
Einrichtung von Fehlerbehebungsberichten vorbereiten
Führen Sie vor dem Einrichten von Fehlerbehebungsberichten die folgenden Schritte aus:
Prüfen Sie, ob Sie die Best Practices für die API-Integration angewendet haben
Stellen Sie sicher, dass Ihr Code durch eine Funktionserkennung geschützt ist. Führen Sie den folgenden Code aus, damit die API nicht durch die Berechtigungsrichtlinie blockiert wird:
if (document.featurePolicy.allowsFeature('attribution-reporting')) { // the Attribution Reporting API is enabled }
Wenn diese Prüfung zur Featureerkennung den Wert „true“ zurückgibt, ist die API in dem Kontext (auf der Seite) zulässig, in dem die Prüfung ausgeführt wird.
(In der Testphase nicht erforderlich: Prüfen Sie, ob Sie eine Permissions-Policy festgelegt haben.)
Grundlegende Integrationsprobleme beheben
Debug-Berichte sind nützlich, um Verluste in großem Umfang zu erkennen und zu analysieren. Einige Integrationsprobleme können jedoch lokal erkannt werden. Fehlerhafte Quell- und Trigger-Header, Probleme beim JSON-Parsing, unsicherer Kontext (Nicht-HTTPS) und andere Probleme, die das Funktionieren der API verhindern, werden auf dem Tab Probleme der Entwicklertools angezeigt.
Es gibt verschiedene Probleme mit den Entwicklertools. Wenn ein invalid header
-Problem auftritt, kopieren Sie den Header in das Header-Validierungstool. So können Sie das Feld, das ein Problem verursacht, leichter identifizieren und beheben.
Debug-Berichte einrichten: Häufige Schritte für Erfolgsberichte und ausführliche Berichte
Setzen Sie das folgende Cookie für den Ursprung der Berichterstellung:
Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly
Der Browser prüft sowohl bei der Quelle als auch bei der Trigger-Registrierung, ob dieses Cookie vorhanden ist. Der Debug-Bericht über den Erfolg wird nur generiert, wenn das Cookie zu beiden Zeitpunkten vorhanden ist.
Fehlerbehebungsberichte können für Browser im Modus B aktiviert werden. Dort sind Drittanbieter-Cookies deaktiviert, um das Testen und die Vorbereitung auf die Einstellung von Drittanbieter-Cookies zu erleichtern. Bei Browsern im Modus B müssen Sie das Debugging-Cookie nicht setzen, um Debug-Berichte zu aktivieren. Fahren Sie mit Schritt 2 fort, um Schlüssel für erfolgreiche Fehlerbehebungsberichte einzurichten.
Schritt 2: Schlüssel für die Fehlerbehebung festlegen
Jeder Schlüssel zur Fehlerbehebung muss eine vorzeichenlose 64-Bit-Ganzzahl sein, die als Base-10-String formatiert ist. Weisen Sie jedem Schlüssel zur Fehlerbehebung eine eindeutige ID zu. Der Bericht zur erfolgreichen Fehlerbehebung wird nur generiert, wenn die Fehlerbehebungsschlüssel festgelegt sind.
- Ordnen Sie den quellseitigen Fehlerbehebungsschlüssel zusätzlichen Informationen zur Quelle zu, die Ihrer Meinung nach für die Fehlerbehebung relevant sind.
- Ordnen Sie den Trigger-seitigen Fehlerbehebungsschlüssel zusätzlichen Informationen zum Trigger-Zeitpunkt zu, die Ihrer Meinung nach für die Fehlerbehebung relevant sind.
Sie könnten beispielsweise die folgenden Schlüssel zur Fehlerbehebung festlegen:
- Cookie-ID + Quellzeitstempel als Schlüssel zur Fehlerbehebung für die Quelle (und erfassen Sie denselben Zeitstempel in Ihrem cookiebasierten System)
- Cookie-ID und Trigger-Zeitstempel als Trigger-Fehlerbehebungsschlüssel (und erfassen diesen Zeitstempel in Ihrem cookiebasierten System)
So können Sie Cookie-basierte Conversion-Informationen zum Abrufen der entsprechenden Fehlerbehebungs- oder Attributionsberichte verwenden. Weitere Informationen finden Sie in Teil 3: Cookbook.
Der quellseitige Schlüssel zur Fehlerbehebung sollte sich von source_event_id
unterscheiden, damit Sie einzelne Berichte mit derselben Quellereignis-ID unterscheiden können.
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"
}
Democode: Quellcode zur Fehlerbehebung Democode: Schlüssel zur Fehlerbehebung auslösen
Debug-Berichte zum Erfolg einrichten
Mit dem Beispielcode in diesem Abschnitt werden Berichte zur Fehlerbehebung sowohl für Berichte auf Ereignisebene als auch für aggregierte Berichte generiert. Berichte auf Ereignisebene und aggregierte Berichte verwenden dieselben Fehlerbehebungsschlüssel.
Schritt 3: Endpunkt einrichten, um Berichte zur erfolgreichen Fehlerbehebung zu erfassen
Richten Sie einen Endpunkt ein, um die Debug-Berichte zu erfassen. Dieser Endpunkt sollte dem Hauptendpunkt der Attribution ähneln, mit einem zusätzlichen debug
-String im Pfad:
- Endpunkt für Berichte zur Fehlerbehebung auf Ereignisebene:
https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
- Endpunkt für aggregatable Erfolgsberichte zur Fehlerbehebung:
https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution
- Endpunkt für aggregatable Erfolgsberichte zur Fehlerbehebung:
Wenn eine Attribution ausgelöst wird, sendet der Browser sofort einen Fehlerbehebungsbericht über eine POST
-Anfrage an diesen Endpunkt. Ihr Servercode für die Verarbeitung eingehender Debug-Berichte zum Erfolg kann wie folgt aussehen (hier auf einem Knotenendpunkt):
// 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);
}
);
Democode: Endpunkt für Fehlerbehebungsberichte auf Ereignisebene
Democode: Endpunkt für aggregierte Fehlerbehebungsberichte
Schritt 4: Prüfen, ob Ihre Einrichtung Debug-Berichte zum Erfolg generiert
- Öffnen Sie
chrome://attribution-internals
im Browser. - Das Kästchen Debug-Berichte anzeigen muss sowohl auf dem Tab Berichte auf Ereignisebene als auch auf dem Tab Aggregierbare Berichte angeklickt sein.
- Öffnen Sie die Websites, auf denen Sie Attribution Reporting implementiert haben. Führen Sie die Schritte aus, die Sie zum Erstellen von Attributionsberichten verwenden. Mit diesen Schritten erhalten Sie auch Berichte zur erfolgreichen Fehlerbehebung.
- In
chrome://attribution-internals
:- Prüfen Sie, ob Attributionsberichte korrekt erstellt werden.
- Prüfen Sie auf den Tabs Berichte auf Ereignisebene und Aggregierbare Berichte, ob auch die Berichte zur Fehlerbehebung erstellt werden. Sie erkennen sie in der Liste anhand ihres blauen Pfads
debug
.
- Prüfen Sie auf Ihrem Server, ob der Endpunkt sofort diese Berichte zur erfolgreichen Fehlerbehebung erhält. Prüfen Sie sowohl Berichte auf Ereignisebene als auch aggregierte Berichte zur Fehlerbehebung.
Schritt 5: Berichte zur erfolgreichen Fehlerbehebung beobachten
Ein Bericht zur Fehlerbehebung ist identisch mit einem Attributionsbericht und enthält sowohl den quellseitigen als auch den Trigger-Schlüssel zur Fehlerbehebung.
{
"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"
}
Ausführliche Fehlerbehebungsberichte einrichten
Schritt 3: Ausführliches Debugging in den Quell- und Triggerheadern aktivieren
Legen Sie debug_reporting
in Attribution-Reporting-Register-Source
und Attribution-Reporting-Register-Trigger
auf true
fest.
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
}
Schritt 4: Endpunkt einrichten, um ausführliche Debug-Berichte zu erfassen
Richten Sie einen Endpunkt ein, um die Debug-Berichte zu erfassen. Dieser Endpunkt sollte dem Hauptendpunkt der Attribution ähneln, mit einem zusätzlichen debug/verbose
-String im Pfad:
https://adtech.example/.well-known/attribution-reporting/debug/verbose
Wenn ausführliche Fehlerbehebungsberichte generiert werden und eine Quelle oder ein Trigger nicht registriert ist, sendet der Browser sofort einen ausführlichen Debug-Bericht über eine POST
-Anfrage an diesen Endpunkt. Ihr Servercode zur Verarbeitung eingehender ausführlicher Fehlerbehebungsberichte kann wie folgt aussehen (hier auf einem Knotenendpunkt):
// 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);
}
);
Im Gegensatz zu Berichten zur erfolgreichen Fehlerbehebung gibt es nur einen Endpunkt für ausführliche Berichte. Ausführliche Berichte, die sich auf Ereignisebene und zusammengefasste Berichte auf Ereignisebene beziehen, werden alle an denselben Endpunkt gesendet.
Democode: Endpunkt für ausführliche Debugging-Berichte
Schritt 5: Prüfen, ob ausführliche Fehlerbehebungsberichte generiert werden
Es gibt zwar zahlreiche Arten ausführlicher Fehlerbehebungsberichte, es reicht jedoch aus, nur eine Art ausführlicher Fehlerbehebungsberichte zu verwenden. Wenn diese eine Art ausführlicher Debug-Bericht korrekt erstellt und empfangen wird, werden auch alle Arten von ausführlichen Debug-Berichten korrekt generiert und empfangen, da alle ausführlichen Fehlerbehebungsberichte dieselbe Konfiguration verwenden und an denselben Endpunkt gesendet werden.
- Öffnen Sie
chrome://attribution-internals
im Browser. - Lösen Sie eine Attribution (Conversion) auf Ihrer Website aus, für die Sie Attributionsberichte eingerichtet haben. Da vor dieser Conversion keine Anzeigeninteraktion (Impression oder Klick) erfolgt ist, wird ein ausführlicher Debug-Bericht vom Typ
trigger-no-matching-source
generiert. - Öffnen Sie in
chrome://attribution-internals
den Tab Ausführliche Fehlerbehebungsberichte und prüfen Sie, ob ein ausführlicher Debug-Bericht vom Typtrigger-no-matching-source
generiert wurde. - Prüfen Sie auf Ihrem Server, ob der Endpunkt sofort diesen ausführlichen Debug-Bericht erhalten hat.
Schritt 6: Ausführliche Fehlerbehebungsberichte ansehen
Ausführliche Debugging-Berichte, die zum Zeitpunkt des Triggers generiert werden, enthalten sowohl den quellenseitigen als auch den triggerseitigen Schlüssel zur Fehlerbehebung (falls es eine übereinstimmende Quelle für den Trigger gibt). Ausführliche Fehlerbehebungsberichte, die zum Zeitpunkt der Quelle generiert werden, enthalten den quellseitigen Fehlerbehebungsschlüssel.
Beispiel für eine Anfrage mit ausführlichen Debugging-Berichten, die vom Browser gesendet wurde:
[
{
"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"
}
]
Jeder ausführliche Bericht enthält die folgenden Felder:
Type
- Der Grund für die Generierung des Berichts Informationen zu allen ausführlichen Berichtstypen und zu den Maßnahmen, die je nach Typ zu unternehmen sind, finden Sie in der Referenz zu ausführlichen Berichten in Teil 3: Debugging-Cookbook.
Body
- Inhalt des Berichts. Dies hängt vom Typ ab. Lesen Sie die ausführlichen Berichte in Teil 3: Debugging-Cookbook.
Der Text einer Anfrage enthält mindestens einen und höchstens zwei ausführliche Berichte:
- Ein ausführlicher Bericht, wenn der Fehler sich nur auf Berichte auf Ereignisebene oder nur auf aggregierte Berichte auswirkt Ein Registrierungsfehler bei einer Quelle oder einem Trigger hat nur einen Grund. Daher kann für jeden Fehler und jeden Berichtstyp (auf Ereignisebene oder aggregierbar) ein ausführlicher Bericht erstellt werden.
- Zwei ausführliche Berichte, wenn sich der Fehler sowohl auf Berichte auf Ereignisebene als auch auf aggregierte Berichte auswirkt – mit einer Ausnahme: Wenn die Fehlerursache für Berichte auf Ereignisebene und für aggregierte Berichte identisch ist, wird nur ein ausführlicher Bericht erstellt (Beispiel:
trigger-no-matching-source
)