Diese Seite wurde von der Cloud Translation API übersetzt.

Fehlerbehebungsberichte für Attribution Reporting einrichten

Teil 2 von 3 zur Fehlerbehebung in Attribution Reporting. Debug-Berichte einrichten

Glossar

Der Ursprung des Berichts ist der Ursprung, mit dem die Header für die Quelle und den 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 Beispiel für den Ursprung der Berichterstellung.
Ein Attributionsbericht (kurz Bericht) ist der endgültige Bericht (auf Ereignisebene oder aggregierbar), der die von Ihnen angeforderten Messdaten enthält.
Ein Bericht zur Fehlerbehebung 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 etwas nicht stimmt. Es gibt zwei Arten von Berichten zur Fehlerbehebung.
Ein Transitional-Debug-Bericht ist ein Debug-Bericht, für den ein Cookie festgelegt werden muss, damit er generiert und gesendet werden kann. Berichte zur vorübergehenden Fehlerbehebung sind nicht mehr verfügbar, wenn kein Cookie gesetzt ist und sobald Drittanbieter-Cookies eingestellt werden. Alle in diesem Leitfaden beschriebenen Fehlerbehebungsberichte sind vorübergehende Debug-Berichte.
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.
In ausführlichen Fehlerbehebungsberichten können Sie fehlende Berichte verfolgen und feststellen, warum sie fehlen. Sie weisen auf Fälle hin, in denen der Browser eine Quelle oder ein Ereignis nicht ausgelöst hat, sodass kein Attributionsbericht erstellt wird, oder wenn ein Attributionsbericht aus irgendeinem Grund nicht erstellt oder gesendet werden kann. Ausführliche Fehlerbehebungsberichte enthalten das Feld type, in dem beschrieben wird, warum ein Quellereignis, ein Triggerereignis oder ein Attributionsbericht nicht generiert wurde. Ausführliche Fehlerbehebungsberichte sind ab Chrome 109 verfügbar (stabil ab Januar 2023).
Schlüssel zur Fehlerbehebung sind eindeutige Kennungen, die Sie sowohl auf der Quell- als auch auf der Triggerseite festlegen können. Mit Schlüsseln zur Fehlerbehebung können Sie cookiebasierte und Attributionsbasierte Conversions zuordnen. Wenn Sie Ihr System so eingerichtet haben, dass Fehlerbehebungsberichte generiert und Schlüssel zur Fehlerbehebung festgelegt werden, nimmt der Browser diese Schlüssel zur Fehlerbehebung in alle Attributionsberichte und Fehlerbehebungsberichte auf.

Weitere Konzepte und wichtige Begriffe, 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.

Democode: Debug-Cookie

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

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.

Screenshot: Logs des Ursprungsservers für die Berichterstellung

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
}

Democode: source-header

Democode: Trigger-Header

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.

Wichtig:Wählen Sie einen ausführlichen Debug-Bericht aus, der leicht zu testen ist. trigger-no-matching-source ist ein guter Kandidat, da Sie ihn durch Konvertierung generieren können. Ausführliche Berichte, die sich auf das Auslösen von Ereignissen beziehen, sind in der Regel besser geeignet. Ausführliche Berichtstypen mit Bezug auf Quellereignisse sind mühsamer und zielgerichteter.

Ö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 Typ trigger-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)

Nächstes Video

Teil 3: Debugging-Cookbook