此页面由 Cloud Translation API 翻译。

为归因报告设置调试报告

有关调试 Attribution Reporting 的第 2 部分（共 3 部分）。设置调试报告。

术语库

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

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

实施方面的问题？

如果您在设置调试报告时遇到任何问题，请在以下位置创建问题：我们的开发者支持团队代码库，我们将帮助您排查问题。

准备设置调试报告

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

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

检查您的代码是否受功能检测的保护。为了确保 API 未被 Permissions-Policy 屏蔽，请运行以下代码：
```
if (document.featurePolicy.allowsFeature('attribution-reporting')) {
// the Attribution Reporting API is enabled
}
```
如果此功能检测检查返回 true，则允许在运行检查的上下文（页面）。
（测试阶段无需执行此操作：检查您是否设置了 Permissions-Policy）

。

修复基本集成问题

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

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

设置调试报告：成功报告和详细报告的常见步骤

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

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

浏览器将检查来源和网站上是否存在此 Cookie 触发器注册。只有在以下情况下，系统才会生成成功调试报告： Cookie。

演示代码：调试 Cookie

请注意，您可以在处于“模式”下的浏览器上启用调试报告 B，其中但会停用第三方 Cookie 以方便测试和准备，第三方 Cookie 弃用。对于模式 B 下的浏览器，您不需要设置调试 Cookie 以启用调试报告。跳至第 2 步以设置调试密钥用于成功调试报告。

第 2 步：设置调试密钥

每个调试密钥都必须是 64 位无符号整数，格式为 base-10 字符串。为每个调试密钥设置唯一 ID。系统仅会生成成功调试报告如果设置了调试密钥，则会发生此错误。

将源代码端调试键映射到调试。
将触发器端调试键映射到您定义的其他触发时间信息调试。

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

将 Cookie ID + 来源时间戳作为来源调试键（并捕获相同的时间戳）时间戳）
将 Cookie ID + 触发时间戳作为触发器调试键（并捕获相同的时间戳）时间戳）

这样，您就可以使用基于 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"
}

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

设置成功调试报告

本部分中的示例代码会针对上述两种情况生成成功调试报告事件级报告和可汇总报告。事件级报告和可汇总报告使用相同的调试密钥。

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

设置端点以收集调试报告。此端点应类似于主归因端点，并在路径中额外添加一个 debug 字符串：

事件级成功调试报告的端点： https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
- aggregatable 成功调试报告的端点： 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。
确保选中 Show Debug Reports 复选框， 事件级报告和可汇总报告标签页。
打开已实现 Attribution Reporting 的网站。完整播放率生成归因报告的步骤；相同的步骤生成成功调试报告。
在 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 中将 debug_reporting 都设置为 true。和 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
}

演示代码：源代码标题

演示代码：触发器标题

第 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是一个很好的候选对象，因为您可以通过转化来生成相关的详细报告往往是更合适的选择；这些报告类型与来源事件相关，刻意生成会更乏味。

在浏览器中打开 chrome://attribution-internals。
在您的网站上触发使用归因工具设置的归因（转化）操作报告。假设没有发生广告互动（展示或点击）在此转换之前，您应该会收到以下类型的详细调试报告：将生成trigger-no-matching-source。
在 chrome://attribution-internals 中，打开 Verbose debug reports（详细调试报告）标签页并检查 trigger-no-matching-source 类型的详细调试报告已生成。
在您的服务器上，验证端点是否立即收到此详细调试报告。

第 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 部分：调试实战宝典。

请求正文将包含至少 1 到最多 2 份详细报告：

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

接下来播放

第 3 部分：调试实战宝典