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

报告来源是用于设置归因报告来源和触发器标头的来源。浏览器生成的所有报告都会发送到此源。在本指南中，我们使用 https://adtech.example 作为示例报告来源。
归因报告（简称“报告”）是包含您请求的衡量数据的最终报告（事件级报告或可汇总报告）。
调试报告包含有关归因报告或者来源或触发器事件的其他数据。收到调试报告并不一定表示存在问题！调试报告有两种
过渡调试报告是一种调试报告，需要设置 Cookie 才能生成和发送。如果 Cookie 未设置且第三方 Cookie 被弃用，过渡调试报告将不可用。本指南中描述的所有调试报告都是过渡性调试报告。
成功调试报告用于跟踪成功生成归因报告。它们与归因报告直接相关。从 Chrome 101（2022 年 4 月）开始，已提供成功调试报告。
详细调试报告可以跟踪缺失的报告，并帮助您确定缺失报告的原因。它们分别用于表明浏览器未记录来源或触发器事件（这意味着浏览器不会生成归因报告）以及由于某种原因无法生成或发送归因报告的情况。详细调试报告包含一个 type 字段，用于说明未生成来源事件、触发器事件或归因报告的原因。从 Chrome 109（2023 年 1 月稳定版）开始提供详细调试报告。
调试键是您可以在来源端和触发器端设置的唯一标识符。通过调试键，您可以映射基于 Cookie 的转化和基于归因的转化。将系统设置为生成调试报告并设置调试密钥后，浏览器会将这些调试密钥添加到所有归因报告和调试报告中。

如需了解我们的文档中使用的更多概念和关键术语，请参阅 Privacy Sandbox 术语表。

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