为归因报告设置调试报告

关于调试归因报告的第 2 部分（共 3 部分）。设置调试报告。

注意：本文是调试 Attribution Reporting API 的系列文章中的一篇。本系列文章介绍了如何对事件级报告和可汇总报告进行客户端调试。GitHub 上提供了摘要报告的服务器端调试指南。

术语库

• The reporting origin is the origin that [sets the Attribution Reporting source and trigger headers. All reports generated by the browser are sent to this origin. In this guidance, we use https://adtech.example as the example reporting origin.
• An attribution report (report for short) is the final report (event-level or aggregatable) that contains the measurement data you've requested.
• A debug report contains additional data about an attribution report, or about a source or trigger event. Receiving a debug report does not necessarily mean that something is working incorrectly! There are two types of debug reports
• A transitional debug report is a debug report that requires a cookie to be set in order to be generated and sent. Transitional debug reports will be unavailable if a cookie is not set, and once third-party cookies are deprecated. All debug reports described in this guide are transitional debug reports.
• Success debug reports track successful generation of an attribution report. They relate directly to an attribution report. Success debug reports have been available since Chrome 101 (April 2022).
• Verbose debug reports can track missing reports and help you determine why they're missing. They indicate cases where the browser did not record a source or trigger event, (which means it will not generate an attribution report), and cases where an attribution report can't be generated or sent for some reason. Verbose debug reports include a type field that describes the reason why a source event, trigger event or attribution report was not generated. Verbose debug reports are available starting in Chrome 109 (Stable in January 2023).
• Debug keys are unique identifiers you can set on both the source side and the trigger side. Debug keys enable you to map cookie-based conversions and attribution-based conversions. When you've set up your system to generate debug reports and set debug keys, the browser will include these debug keys in all attribution reports and debug reports.

For more concepts and key terms used throughout our documentation, refer to the Privacy Sandbox glossary.

有实施方面的问题？

如果您在设置调试报告时遇到任何问题，请在我们的开发者支持仓库中创建问题，我们将帮助您排查问题。

准备设置调试报告

在设置调试报告之前，请按以下步骤操作：

检查您是否采用了 API 集成的最佳实践

• 检查您的代码是否受功能检测控制。如需确保该 API 不会被 Permissions-Policy 屏蔽，请运行以下代码：

  if (document.featurePolicy.allowsFeature('attribution-reporting')) {
  // the Attribution Reporting API is enabled
  }
  

  如果此功能检测检查返回 true，则系统会在运行该检查的上下文（页面）中允许该 API。

• （测试阶段不需要：检查您是否设置了 Permissions-Policy）

要点：对于测试，系统已放宽了权限政策要求，但发布商或广告主仍然可以决定使用权限政策来明确停用 Attribution Reporting API。在这种情况下，无法记录任何来源或触发器（因此，无法生成或发送任何报告）。

解决基本集成问题

虽然调试报告有助于您大规模检测和分析损失，但一些集成问题可在本地检测出来。开发者工具问题标签页中会显示来源和触发器标头配置错误、JSON 解析问题、不安全上下文（非 HTTPS）以及其他阻止 API 正常运行的问题。

注意：这些问题不会生成详细的调试报告，因为它们会导致 API 无法正常运行。只有缺少成功调试报告才表示您可能会遇到其中一些问题。如需了解详情，请参阅第 3 部分：调试实战宝典。

开发者工具问题可能有多种类型。如果您遇到 invalid header 问题，请将标头复制到标头验证工具中。这将有助于您找出并修正导致问题的字段。

设置调试报告：成功报告和详细报告通用的步骤

第 1 步：设置调试 Cookie

在报告来源上设置以下 Cookie：

Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly

浏览器将在来源注册和触发器注册时检查是否存在此 Cookie。仅当 Cookie 同时存在时，系统才会生成成功调试报告。

演示代码：调试 Cookie

请注意，可以为处于模式 B 的浏览器启用调试报告，在模式 B 下，系统会停用第三方 Cookie，以方便测试和准备弃用第三方 Cookie。对于模式 B 的浏览器，您无需设置调试 Cookie 即可启用调试报告。跳至第 2 步，为成功调试报告设置调试密钥。

第 2 步：设置调试密钥

每个调试密钥都必须是一个 64 位无符号整数，格式为以 10 为底数的字符串。 将每个调试密钥设为唯一 ID。只有在设置了调试密钥时，系统才会生成成功调试报告。

• 将源代码端调试密钥映射到您认为与调试相关的其他源代码时信息。
• 将触发器端调试键映射到您认为与调试相关的其他触发器时间信息。

例如，您可以设置以下调试键：

• 作为来源调试键的 Cookie ID + 来源时间戳（并在基于 Cookie 的系统中捕获相同的时间戳）
• Cookie ID + 触发器时间戳作为触发器调试键（并在基于 Cookie 的系统中捕获相同的时间戳）

这样，您就可以使用基于 Cookie 的转化信息来查询相应的调试报告或归因报告。如需了解详情，请参阅第 3 部分：实战宝典。

将来源端调试键设置为与 source_event_id 不同，以便区分具有相同来源事件 ID 的各个报告。

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"
}

演示代码：源调试密钥 演示代码：触发调试密钥

注意：在演示代码中，我们为两个调试键提供了旧版衡量第三方 Cookie 的值。在实际系统中，您可以将每个键设为一个唯一 ID，并将其映射到您认为可用于调试的其他源代码时信息，如上面的调试键示例所示。

设置成功调试报告

注意：请尝试使用演示在浏览器中生成并预览成功调试报告。查看相应的代码。

本部分中的示例代码会针对事件级报告和可汇总报告生成成功调试报告。事件级报告和可汇总报告使用相同的调试键。

第 3 步：设置端点以收集成功调试报告

设置一个用于收集调试报告的端点。此端点应类似于主要归因端点，且路径中包含一个额外的 debug 字符串：

• 事件级成功调试报告的端点： https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
  • 可汇总的成功调试报告的端点：https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution

触发归因后，浏览器会立即通过 POST 请求向此端点发送调试报告。用于处理收到的成功调试报告的服务器代码可能如下所示（此处是节点端点）：

// 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);
  }
);

演示代码：事件级调试报告端点

演示代码：可汇总的调试报告端点

第 4 步：确认您的设置将生成成功调试报告

• 在浏览器中打开 chrome://attribution-internals。
• 确保已选中“事件级报告”和“可汇总报告”标签页中的“显示调试报告”复选框。
• 打开已实现归因报告的网站。完成用于生成归因报告的步骤；这些步骤将生成成功调试报告。
• 在 chrome://attribution-internals 中：
  • 检查是否已正确生成归因报告。
  • 在“事件级报告”和“可汇总的报告”标签页中，检查是否也生成了成功调试报告。使用蓝色 debug 路径在列表中识别它们。

• 在您的服务器上，验证您的端点是否会立即收到这些成功调试报告。请务必查看事件级成功调试报告和可汇总的成功调试报告。

第 5 步：观察成功调试报告

成功调试报告与归因报告相同，其中包含来源端和触发器端调试键。

{
  "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"
}

设置详细调试报告

注意：您可以尝试在浏览器中生成和预览详细调试报告演示。 查看相应的代码。

第 3 步：在来源和触发器标头中选择详细调试

在 Attribution-Reporting-Register-Source 和 Attribution-Reporting-Register-Trigger 中将 debug_reporting 设置为 true。

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
}

演示代码：源标头

演示代码：触发器标头

第 4 步：设置端点以收集详细调试报告

设置一个用于收集调试报告的端点。此端点应该类似于主要归因端点，且路径中包含一个额外的 debug/verbose 字符串：

https://adtech.example/.well-known/attribution-reporting/debug/verbose

生成详细调试报告后，即未注册来源或触发器时，浏览器将通过 POST 请求立即向此端点发送详细调试报告。用于处理传入的详细调试报告的服务器代码可能如下所示（在节点端点上）：

// 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);
  }
);

与成功调试报告不同，详细报告只有一个端点。与事件级报告和汇总报告相关的详细报告都将发送到同一端点。

演示代码：详细调试报告端点

第 5 步：确认您的设置将生成详细调试报告

虽然详细的调试报告有很多种，但只使用一种类型的详细调试报告检查详细调试设置就足够了。如果正确生成并接收了这种类型的详细调试报告，这意味着系统也将正确生成和接收所有类型的详细调试报告，因为所有详细调试报告都使用相同的配置并被发送到同一端点。

要点：选择易于测试的详细调试报告。trigger-no-matching-source 是一个很好的候选版本，因为您可以通过转换来生成此令牌。与触发事件相关的详细报告往往是更好的候选类型；与来源事件相关的详细报告类型则更冗长乏味。

1. 在浏览器中打开 chrome://attribution-internals。
2. 在使用归因报告设置的网站上触发归因（转化）。鉴于在此次转化之前没有发生广告互动（展示或点击），您应该应该会生成 trigger-no-matching-source 类型的详细调试报告。
3. 在 chrome://attribution-internals 中，打开详细调试报告标签页，然后检查是否已生成 trigger-no-matching-source 类型的详细调试报告。
4. 在您的服务器上，验证您的端点是否已立即收到此详细调试报告。

第 6 步：查看详细调试报告

在触发器时生成的详细调试报告包含来源端和触发器端调试密钥（如果有与触发器匹配的来源）。在源代码时生成的详细调试报告包含来源端调试密钥。

包含详细调试报告的请求示例，由浏览器发送：

[
  {
    "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"
  }
]

要点：与成功调试请求不同，详细调试请求在其正文中包含详细报告的列表（数组）。

每份详细报告包含以下字段：

Type

导致生成报告的原因。如需了解所有详细报告类型以及针对每种类型采取的操作，请参阅第 3 部分：调试实战宝典中的详细报告参考文档。

Body

报告的正文。具体取决于其类型。请参阅第 3 部分：调试实战宝典中的详细报告参考文档。

请求正文至少包含两个详细报告：

• 如果失败结果仅影响事件级报告（或者仅影响可汇总报告），则生成一份详细报告。来源或触发器注册失败的原因只有一种；因此，系统可以针对每种失败和每种报告类型（事件级或可汇总）生成一份详细报告。
• 如果失败同时影响事件级报告和可汇总报告，则提供两种详细报告，但有一个例外情况：如果事件级报告和可汇总报告的失败原因相同，则仅生成一份详细报告（例如：trigger-no-matching-source）

接下来播放

第 3 部分：调试实战宝典