移动版归因报告概览

近期更新

  • 更新了即将发生的所有调整和已知问题列表

  • 引入了精简版灵活事件级配置，作为通往完整版灵活事件级配置的桥梁

  • 自 2023 年 9 月起，registerWebSource、registerWebTrigger、registerAppSource 和 registerAppTrigger 必须为预期采用数字值的字段（如 priority、source_event_id、debug_key、trigger_data、deduplication_key 等）使用字符串

  • 在 2023 年第 4 季度，会添加 Android Attribution Reporting API 中的 Google Cloud 支持，以便利用 Google Cloud 上的汇总服务生成摘要报告，更具体的时间信息请参阅本文。如需详细了解如何使用 Google Cloud 设置汇总服务，请参阅部署指南。

  • 针对唯一目标数量新增了可保护隐私的速率限制。

  • 我们将于 2024 年第 1 季度推出适用于回溯期触发器过滤条件的更新版功能，如需了解详情，请参阅备注。

概览

现在，移动归因和效果衡量解决方案经常会使用跨多方标识符，例如广告 ID。Attribution Reporting API 旨在通过消除对跨多方用户标识符的依赖来更好地保护用户隐私，并支持跨应用和跨网站进行归因和转化衡量的关键用例。

该 API 具有以下结构机制，这些机制提供了一个用于加强隐私保护的框架，本页后面几个部分将详细说明：

上述机制可限制跨两个不同应用或网域关联用户身份的能力。

Attribution Reporting API 支持以下用例：

  • 转化报告：通过向广告主显示各个维度（例如广告系列、广告组和广告素材）的转化（触发器）次数和转化（触发器）值，协助广告主衡量其广告系列的效果。
  • 优化：通过提供可用于训练机器学习模型的每次展示归因数据，提供有助于优化广告支出的事件级报告。
  • 无效活动检测：提供可用于无效流量和广告欺诈检测与分析的报告。

概括来讲，Attribution Reporting API 的运作方式如下（本文档后面几个部分将详细说明）：

  1. 广告技术平台完成注册流程，以使用 Attribution Reporting API。
  2. 广告技术平台向 Attribution Reporting API 注册归因来源（广告点击或观看）。
  3. 广告技术平台向 Attribution Reporting API 注册触发器（广告主应用或网站上的用户转化）。
  4. Attribution Reporting API 将触发器与归因来源进行匹配（一种转化归因），并且一个或多个触发器通过事件级报告和可汇总报告发送到设备外的广告技术平台。

获取对 Attribution Reporting API 的访问权限

广告技术平台需要注册才能访问 Attribution Reporting API。如需了解详情，请参阅注册 Privacy Sandbox 账号。

注册归因来源（点击或观看）

Attribution Reporting API 会将广告点击和观看作为归因来源。如需注册广告点击或广告观看，请调用 registerSource()。该 API 需要以下参数：

  • 归因来源 URI：平台将向此 URI 发出请求，以便获取与归因来源关联的元数据。
  • 输入事件：InputEvent 对象（如果是点击事件）或 null（如果是观看事件）。

当该 API 向归因来源 URI 发出请求时，广告技术平台应使用新的 HTTP 标头 Attribution-Reporting-Register-Source 返回归因来源元数据进行响应，这些元数据中包含以下字段：

  • Source event ID：该值表示与相应归因来源（广告点击或观看）关联的事件级数据，必须为字符串格式的 64 位无符号整数。
  • Destination：一个来源，其 eTLD+1 或应用软件包名称表示触发器事件的发生位置。
  • Expiry（可选）：过期时间（以秒为单位），超过该时间后应从设备中删除相应来源。默认值为 30 天，最小值为 1 天，最大值为 30 天。该值会四舍五入到最接近的天数，格式可以为 64 位无符号整数或字符串。
  • Event report window（可选）：注册来源后的时长（以秒为单位），在此时间段内系统可以针对此来源创建事件报告。如果事件报告期限已过，但过期时间尚未过去，那么触发器仍可以与来源匹配，但系统不会针对该触发器发送事件报告。报告期限不得大于过期时间，格式可以为 64 位无符号整数或字符串。
  • Aggregatable report window（可选）：注册来源后的时长（以秒为单位），在此时间段内系统可以针对此来源创建可汇总报告。报告期限不得大于过期时间，格式可以为 64 位无符号整数或字符串。
  • Source priority（可选）：在有多个归因来源可与指定的触发器相关联时，用于选择该触发器应与哪个归因来源相关联。必须为字符串格式的 64 位有符号整数。

    收到触发器后，该 API 会查找来源优先级值最高的匹配归因来源，并生成报告。每个广告技术平台都可以定义自己的优先级策略。如需详细了解优先级对归因有何影响，请参阅优先级示例部分。

    值越高，表示优先级越高。
  • Install and post-install attribution windows（可选）：用于确定安装后事件的归因，本页后面的部分将对其进行介绍。
  • Filter data（可选）：用于选择性地过滤某些触发器，实际上是忽略它们。如需了解详情，请参阅本页的触发器过滤条件部分。
  • Aggregation keys（可选）：指定用于细分可汇总报告内容的键。

归因来源元数据响应可能会根据需要在归因报告重定向标头中包含其他数据。这些数据包含重定向网址，可供多个广告技术平台注册请求。

开发者指南提供了一些展示如何接受来源注册的示例。

以下步骤显示了一个示例工作流程：

  1. 广告技术 SDK 调用该 API 以启动归因来源注册，并指定该 API 要调用的 URI：

    registerSource(
    Uri.parse("https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA"),
    myClickEvent);

  2. 该 API 使用以下标头之一向 https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA 发出请求：

    <!-- For click events -->
Attribution-Reporting-Source-Info: navigation

<!-- For view events -->
Attribution-Reporting-Source-Info: event

  3. 该广告技术平台的 HTTPS 服务器使用包含以下内容的标头进行回复：

    Attribution-Reporting-Register-Source: {
    "destination": "android-app://com.advertiser.example",
    "source_event_id": "234",
    "expiry": "60000",
    "priority": "5"
}
Attribution-Reporting-Redirect:
https://adtechpartner1.example?their_ad_click_id=567
Attribution-Reporting-Redirect:
https://adtechpartner2.example?their_ad_click_id=890

  4. 该 API 向 Attribution-Reporting-Redirect 中指定的每个网址发出请求。在本示例中，指定了两个广告技术合作伙伴网址，因此 API 将向 https://adtechpartner1.example?their_ad_click_id=567 发出一个请求，并向 https://adtechpartner2.example?their_ad_click_id=890 发出另一个请求。

  5. 该广告技术平台的 HTTPS 服务器使用包含以下内容的标头进行回复：

    Attribution-Reporting-Register-Source: {
    "destination": "android-app://com.advertiser.example",
    "source_event_id": "789",
    "expiry": "120000",
    "priority": "2"
}

根据前面的步骤中所述的请求，注册了三个导航（点击）归因来源。

通过 WebView 注册归因来源

WebView 支持以下用例：应用在 WebView 中呈现广告。这由 WebView 直接调用 registerSource() 作为后台请求进行处理。此调用会将归因来源与应用（而不是顶级来源）相关联。系统也支持在浏览器上下文内注册嵌入式 Web 内容中的来源；为此，API 调用方和应用都需要调整设置。有关 API 调用方的说明，请参阅通过 WebView 注册归因来源和触发器；有关应用的说明，请参阅通过 WebView 进行的归因来源和触发器注册。

由于广告技术平台在 Web 和 WebView 中使用通用代码，因此 WebView 会遵循 HTTP 302 重定向并将有效注册信息传递给平台。对于这种情境，我们不打算支持 Attribution-Reporting-Redirect 标头，但如果您有受影响的用例，请与我们联系。

注册触发器（转化）

广告技术平台可以使用 registerTrigger() 方法注册触发器，即转化（例如安装或安装后事件）。

registerTrigger() 方法需要触发器 URI 参数。该 API 会向此 URI 发出请求，以便获取与触发器关联的元数据。

该 API 会跟踪重定向。广告技术服务器响应应包含一个称为 Attribution-Reporting-Register-Trigger 的 HTTP 标头，该标头表示关于一个或多个已注册触发器的信息。标头的内容应经过 JSON 编码，并且包含以下字段：

  • Trigger data：该数据用于识别触发器事件（如果是 3 位，则表示点击；如果是 1 位，则表示观看），必须为字符串格式的 64 位有符号整数。

  • Trigger priority（可选）：表示相应触发器相对于同一归因来源的其他触发器的优先级，必须为字符串格式的 64 位有符号整数。如需详细了解优先级对报告有何影响，请参阅优先级部分。

  • Deduplication key（可选）：用于识别以下情况：同一广告技术平台针对同一归因来源多次注册了同一触发器。必须为字符串格式的 64 位有符号整数。

  • Aggregation keys（可选）：一个字典列表，用于指定汇总键以及哪些可汇总的报告应汇总它们的值。

  • Aggregation values（可选）：对每个键有贡献的值的列表。

  • Filters（可选）：用于选择性地过滤触发器或触发器数据。如需了解详情，请参阅本页的触发器过滤条件部分。

（可选）广告技术平台服务器响应可能会在归因报告重定向标头中包含其他数据。这些数据包含重定向网址，可供多个广告技术平台注册请求。

多个广告技术平台可以使用 Attribution-Reporting-Redirect 字段中的重定向或多次调用 registerTrigger() 方法来注册同一触发器事件。我们建议您使用 Deduplication key 字段，以避免在同一个广告技术平台为同一个触发器事件提供了多个响应时，报告中包含重复的触发器。详细了解如何以及何时使用重复信息删除键。

开发者指南提供了一些展示如何接受触发器注册的示例。

以下步骤显示了一个示例工作流程：

  1. 广告技术平台 SDK 会调用该 API，以使用预先注册的 URI 来启动触发器注册：如需了解详情，请参阅注册 Privacy Sandbox 账号。

    registerTrigger(
    Uri.parse("https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA"));

  2. 该 API 会向 https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA 发出请求。

  3. 该广告技术平台的 HTTPS 服务器使用包含以下内容的标头进行回复：

    Attribution-Reporting-Register-Trigger: {
    "event_trigger_data": [{
    "trigger_data": "1122",
    // This returns 010 for click-through conversions (CTCs) and 0 for
    // view-through conversions (VTCs) in reports
    "priority": "3",
    "deduplication_key": "3344"
    }],
}
Attribution-Reporting-Redirect: https://adtechpartner.example?app_install=567

  4. 该 API 向 Attribution-Reporting-Redirect 中指定的每个网址发出请求。在此示例中，因为仅指定了一个网址，所以该 API 会向 https://adtechpartner.example?app_install=567 发出请求。

  5. 该广告技术平台的 HTTPS 服务器使用包含以下内容的标头进行回复：

    Attribution-Reporting-Register-Trigger: {
"event_trigger_data":[{
  "trigger_data": "5566",
  "priority": "3",
  "deduplication_key": "3344"
}]
}

    根据前面步骤中的请求注册了两个触发器。

归因功能

以下几部分将介绍 Attribution Reporting API 如何将转化触发器与归因来源进行匹配。

采用了来源优先归因算法

Attribution Reporting API 采用了来源优先归因算法，以便将触发器（转化）与归因来源进行匹配。

您可以通过优先级参数自定义触发器的归因来源：

  • 您可以将触发器归因于特定广告事件，优先于其他事件。例如，您可以选择更注重点击而非观看，或者重点关注来自某些广告系列的事件。
  • 您可以配置归因来源和触发器，以便在达到速率限制时更有可能收到对您更重要的报告。例如，您可能希望确保可出价转化或高价值转化有更大的机会出现在这些报告中。

如果多个广告技术平台注册了一个归因来源（如本页下文所述），那么系统会针对每个广告技术平台独立进行这项归因。对于每个广告技术平台，触发器事件都会归因于优先级最高的归因来源。如果存在多个具有相同优先级的归因来源，该 API 会选择最后注册的归因来源。未被选中的所有其他归因来源都会被舍弃，并且不再符合参与后续触发器归因的条件。

触发器过滤条件

来源注册和触发器注册包含额外的可选功能，用于执行以下操作：

  • 选择性地过滤某些触发器，从而有效地忽略它们。
  • 根据来源数据为事件级报告选择触发器数据。
  • 选择从事件级报告中排除某个触发器。

如需选择性地过滤触发器，广告技术平台可以在来源注册和触发器注册期间指定过滤条件数据（由键和值组成）。如果为来源和触发器指定了相同的键，那么当交集为空时，系统会忽略触发器。例如，来源可以指定 "product": ["1234"]，其中 product 是过滤条件的键，1234 是值。如果触发器过滤条件设置为 "product": ["1111"]，就会忽略该触发器。如果没有与 product 匹配的触发器过滤条件的键，就会忽略这些过滤条件。

广告技术平台可能需要选择性过滤触发器的另一个场景，就是为了强制缩短过期时间。在触发器注册时，广告技术平台可以指定（以秒为单位）自转化发生时间起的回溯期；例如，7 天的回溯期将定义为："_lookback_window": 604800 // 7d

为了判断某个过滤条件是否匹配，该 API 会先检查回溯期。自来源注册以来的时长（如果有）必须短于或等于回溯期的时长。

广告技术平台也可以根据来源事件数据选择触发器数据。例如，API 会将 source_type 自动生成为 navigation 或 event。在触发器注册期间设置 trigger_data 时，可针对 "source_type": ["navigation"] 设置为一个值，并针对 "source_type": ["event"] 设置为另一个不同值。

如果满足以下任一条件，便会从事件级报告中排除触发器：

  • 未指定 trigger_data。
  • 来源和触发器指定了相同的过滤条件键，但值不一致。请注意，在这种情况下，事件级报告和可汇总报告都会忽略触发器。

安装后归因

在有些情况下，即使最近发生了其他符合条件的归因来源，也需要将安装后触发器归因于促成安装的同一归因来源。

该 API 允许广告技术平台设置安装后归因期，因此可以支持此用例：

  • 注册归因来源时，请指定安装归因回溯期，即预计发生安装事件的时间范围（通常为 2-7 天，可接受的范围为 1-30 天）。将此时间范围指定为秒数。
  • 注册归因来源时，请指定安装后归因专享回溯期，在此期间内的任何安装后触发器事件都应与促成安装的归因来源相关联（通常为 7-30 天，可接受的范围为 0-30 天）。将此时间范围指定为秒数。
  • Attribution Reporting API 会验证应用安装发生时间，并在内部按照来源优先归因逻辑将安装归因于相应的归因来源。不过，系统不会将安装事件发送到广告技术平台，也不会计入平台各自的速率限制。
  • 应用安装验证适用于任何下载的应用。
  • 安装后归因回溯期内出现的所有后续触发器都归因于与已验证的安装相同的归因来源，前提是该归因来源符合条件。

将来，我们可能会探索通过扩展设计来支持更先进的归因模型。

下表显示了一个示例，展示广告技术平台可以如何使用安装后归因。该示例假设所有归因来源和触发器都由同一广告技术联盟注册，且所有优先级均相同。

事件 事件发生日 备注
点击 1 1 install_attribution_window 设置为 172800（2 天），post_install_exclusivity_window 设置为 864000（10 天）
已验证安装 2 API 在内部对已验证安装进行归因，但这些安装不会被视为触发器。因此，此时不会发送任何报告。
触发器 1（首次打开） 2 广告技术平台注册的首个触发器。在此示例中，它表示首次打开，但可以是任何触发器类型。
归因于点击 1（与已验证安装的归因一致）。
点击 2 4 对 install_attribution_window 和 post_install_exclusivity_window 使用与点击 1 相同的值
触发器 2（安装后） 5 广告技术平台注册的第二个触发器。在此示例中，它表示安装后的转化，例如购买。
归因于点击 1（与已验证安装的归因一致）。
点击 2 被舍弃，不符合参与后续归因的条件。

下面列出了关于安装后归因的一些其他说明：

  • 如果已验证安装并非发生在 install_attribution_window 指定的天数内，就不会应用安装后归因。
  • 已验证安装并非由广告技术平台注册，不会在报告中被发送出去，也不会计入广告技术平台的速率限制。已验证安装仅用于标识归因于安装的归因来源。
  • 在上表的示例中，触发器 1 和触发器 2 分别表示首次打开和安装后转化。不过，广告技术平台可以注册任何类型的触发器。换言之，第一个触发器并不一定要是首次打开。
  • 如果在 post_install_exclusivity_window 到期后注册更多触发器，点击 1 仍符合参与归因的条件（假设该事件尚未过期且尚未达到其速率限制）。
    • 如果注册了优先级更高的归因来源，点击 1 可能仍会丢失或被舍弃。
  • 如果卸载后重新安装广告主应用，会将重新安装计为新的已验证安装。
  • 如果点击 1 是观看事件，“首次打开”和安装后触发器仍会归因于该事件。该 API 限定每次观看只能归因于一个触发器，但安装后归因除外，在此情况下，允许将每次观看归因于最多两个触发器。在安装后归因的情况下，广告技术平台可能会收到 2 个不同的报告期（2 天后或来源有效期）。

支持基于应用的触发器路径和基于网站的触发器路径的所有组合

借助 Attribution Reporting API，可以对单个 Android 设备上的以下触发器路径进行归因：

  • 从应用到应用：用户在某个应用中看到广告，然后在该应用或已安装的其他应用中完成转化。
  • 从应用到网站：用户在某个应用中看到广告，然后在移动浏览器或应用浏览器中完成转化。
  • 从网站到应用：用户在某个移动浏览器或应用浏览器中看到广告，然后在应用中完成转化。
  • 从网站到网站：用户在某个移动浏览器或应用浏览器中看到广告，然后在同一设备上的同一浏览器或其他浏览器中完成转化。

我们允许网络浏览器支持已在网络上公开的新功能，例如与 Privacy Sandbox for the Web's Attribution Reporting API（可以调用 Android API 来实现跨应用和跨网站进行归因）相似的功能。

了解广告技术平台和应用需要做出哪些更改才能支持跨应用和跨网站衡量的触发路径。

为单个归因来源确定多个触发器的优先级

一个归因来源可能会导致多个触发器。例如，购买流程可能会涉及“应用安装”触发器、一个或多个“添加到购物车”触发器和“购买”触发器。每个触发器都会根据来源优先归因算法（本页后面部分将对其进行介绍）归因于一个或多个归因来源。

可归因于单个归因来源的触发器数量有限制。如需了解详情，请参阅本页后面的在归因报告中查看衡量数据部分。

如果有多个触发器超出了这些限制，引入优先级逻辑有助于恢复最有价值的触发器。例如，广告技术平台的开发者可能希望优先获取“购买”触发器，而非“添加到购物车”触发器。

为了支持这种逻辑，可以为触发器设置单独的优先级字段，并且在指定的报告期内，在应用限制之前先选择优先级最高的触发器。

允许多个广告技术平台注册归因来源或触发器

有多个广告技术平台接收归因报告的情况很常见，这通常是为了执行跨广告网络重复信息删除。因此，该 API 允许多个广告技术平台注册同一个归因来源或触发器。广告技术平台必须同时注册归因来源和触发器才能接收来自该 API 的回传，并在广告技术平台向该 API 注册的归因来源和触发器间完成归因。

希望使用第三方执行跨广告网络重复信息删除的广告主可以使用如下所述的方式继续这样做：

  • 设置内部服务器，以注册并从该 API 接收报告。
  • 继续使用现有的移动设备衡量合作伙伴。

归因来源

registerSource() 方法支持归因来源重定向：

  1. 调用 registerSource() 方法的广告技术平台可以在响应中提供一个额外的 Attribution-Reporting-Redirect 字段，该字段表示合作伙伴广告技术的重定向网址集合。
  2. 然后，该 API 会调用重定向网址，以便合作伙伴广告技术平台可以注册归因来源。

Attribution-Reporting-Redirect 字段中可以列出多个合作伙伴广告技术平台网址，但合作伙伴广告技术平台无法指定自己的 Attribution-Reporting-Redirect 字段。

该 API 还允许不同的广告技术平台各自调用 registerSource()。

触发器

对于触发器注册，系统会以类似方式支持第三方：广告技术平台可以使用额外的 Attribution-Reporting-Redirect 字段，也可以各自调用 registerTrigger() 方法。

当广告主使用多个广告技术平台来注册同一个触发器事件时，应使用重复信息删除键。重复信息删除键旨在消除因同一广告技术平台注册同一事件导致的这些重复报告所引发的歧义。例如，某广告技术平台可能以 SDK 直接调用 API 注册了一个触发器，同时又将其网址包含在另一个广告技术平台调用的重定向字段中。如果未提供重复信息删除键，重复的触发器可能会作为不同的触发器回报给每个广告技术平台。

处理重复的触发器

广告技术平台可能会向该 API 多次注册同一触发器。场景包括：

  • 用户多次执行同一操作（触发器）。例如，用户在同一报告期内多次浏览同一产品。
  • 广告主应用使用多个 SDK 进行转化衡量，所有这些 SDK 都会重定向到同一个广告技术平台。例如，广告主应用使用 2 个衡量合作伙伴，即 MMP 1 和 MMP 2。这两个 MMP 都会重定向到广告技术平台 3。当触发器发生时，两个 MMP 都会向 Attribution Reporting API 注册该触发器。然后，广告技术平台 3 收到针对同一触发器的两个单独的重定向：一个来自 MMP 1，另一个来自 MMP 2。

在这些情况下，您可以采用多种方式来抑制关于重复触发器的事件级报告，以降低超出应用于事件级报告的速率限制的可能性。建议使用重复信息删除键。

推荐方法：重复信息删除键

建议广告主应用将唯一的重复信息删除键传递给它用于转化衡量的所有广告技术平台 或 SDK。当发生转化时，该应用会将重复信息删除键传递给广告技术平台或 SDK。然后，这些广告技术平台或 SDK 会继续使用 Attribution-Reporting-Redirect 中所指定网址内的参数将重复信息删除键传递给重定向。

广告技术平台可以选择仅注册具有给定重复信息删除键的第一个触发器，也可以选择注册多个触发器或注册所有触发器。在注册重复的触发器时，广告技术平台可以指定 deduplication_key。

如果广告技术平台使用同一重复信息删除键和归因的来源注册多个触发器，事件级报告中仅会发送第一个已注册的触发器。重复的触发器仍会在加密的可汇总报告中发送。

替代方法：广告技术平台同意为每个广告主采用不同的触发器类型

如果广告技术平台不希望使用重复信息删除键，或广告主应用无法传递重复信息删除键，则可以使用替代选项。衡量指定广告主转化情况的所有广告技术平台必须相互配合，才能为每个广告主定义不同的触发器类型。

启动触发器注册调用的广告技术平台（例如 SDK）会在 Attribution-Reporting-Redirect 中所指定的网址内包含参数（例如 duplicate_trigger_id）。该 duplicate_trigger_id 参数可以包含相应广告主的 SDK 名称和触发器类型等信息。这样一来，广告技术平台便可将这些重复的触发器的一部分发送到事件级报告。广告技术平台还可以在其汇总键中包含此 duplicate_trigger_id。

跨广告网络归因示例

在本部分所述的示例中，广告主使用了两个广告投放技术平台（广告技术平台 A 和广告技术平台 B）和一个衡量合作伙伴 (MMP)。

首先，Adtech A、Adtech B 和 MMP 必须各自完成注册，才能使用 Attribution Reporting API。如需了解详情，请参阅注册 Privacy Sandbox 账号。

下面的列表提供了一系列假设的用户操作（每天发生一个），以及 Attribution Reporting API 如何针对广告技术平台 A、广告技术平台 B 和 MMP 处理这些操作：

第 1 天：用户点击广告技术平台 A 投放的广告

广告技术平台 A 使用其 URI 调用 registerSource()。API 向该 URI 发出请求，并使用广告技术平台 A 的服务器响应中的元数据注册该点击。

广告技术平台 A 还会在 Attribution-Reporting-Redirect 标头中添加 MMP 的 URI。API 向 MMP 的 URI 发出请求，并使用 MMP 服务器响应中的元数据注册该点击。

第 2 天：用户点击广告技术平台 B 投放的广告

广告技术平台 B 使用其 URI 调用 registerSource()。API 向该 URI 发出请求，并使用广告技术平台 B 的服务器响应中的元数据注册该点击。

与广告技术平台 A 一样，广告技术平台 B 同样在 Attribution-Reporting-Redirect 标头中添加了 MMP 的 URI。API 向 MMP 的 URI 发出请求，并使用 MMP 服务器响应中的元数据注册该点击。

第 3 天：用户观看由广告技术平台 A 投放的广告

API 的响应方式与第 1 天相同，只不过会为广告技术平台 A 和 MMP 各注册一次观看。

第 4 天：用户安装应用，该应用使用 MMP 来衡量转化

MMP 使用其 URI 调用 registerTrigger()。API 向该网址发出请求，并使用 MMP 服务器响应中的元数据注册该转化。

MMP 还会在 Attribution-Reporting-Redirect 标头中添加广告技术平台 A 和广告技术平台 B 的 URI。API 向广告技术平台 A 和广告技术平台 B 的服务器发出请求，并使用服务器响应中的元数据相应地注册该转化。

下图展示了前面的列表中所述的流程：

关于 Attribution Reporting API 如何响应一系列用户操作的示例。

归因过程的工作原理如下：

  • 广告技术平台 A 将点击的优先级设为高于观看的优先级，因此将安装归因于第 1 天的点击。
  • 广告技术平台 B 将安装归因于第 2 天。
  • MMP 将点击的优先级设为高于观看的优先级，并将安装归因于第 2 天的点击。第 2 天的点击是优先级最高且最近发生的广告事件。

无重定向的跨广告网络归因

虽然我们建议使用重定向以允许多个广告技术平台注册归因来源和触发器，但我们知道，在某些情况下使用重定向不可行。本部分将详细介绍如何在不进行重定向的情况下支持跨广告网络归因。

概要流程

  1. 在来源注册时，广告投放技术联盟会共享其来源汇总键。
  2. 触发注册时，广告主或衡量合作伙伴会选择要使用的来源端键部分，并指定其归因配置。
  3. 归因取决于归因配置、共享键，以及由该广告主或衡量合作伙伴实际注册的任何来源（例如，其他已启用重定向的广告投放技术联盟）。
  4. 如果触发器归因为来自非重定向广告投放技术的来源，则广告主或衡量合作伙伴可以接收可汇总的报告，其中会汇总第 2 步中定义的来源和触发器键部分。

来源注册

在来源注册时，广告投放技术联盟可以选择共享其来源汇总键或一部分来源汇总键，而不是重定向。广告投放技术平台并不需要在其可汇总报告中实际使用这些来源键，而且可以仅在需要时代表广告主或衡量合作伙伴声明它们。

共享汇总键可供为同一广告主注册触发器的任何广告技术平台使用。不过，广告投放技术平台和触发器衡量广告技术平台将共同协作来决定需要哪些类型的汇总键、其名称，以及如何将这些键解码为可读维度。

触发器注册

在触发器注册时，衡量广告技术平台会选择要将哪些来源端键部分应用于每个触发器键部分，包括广告投放技术平台共享的任何内容。

此外，衡量广告技术平台还必须通过新的归因配置 API 调用来指定广告瀑布流归因逻辑。采用这种配置时，广告技术平台可以指定来源优先级、过期时间并过滤掉其无法查看的来源（例如，未使用重定向的来源）。

归因

Attribution Reporting API 会根据衡量广告技术平台的归因配置、共享键以及所注册的任何来源，为该广告技术平台执行来源优先的最后接触归因。例如：

  • 用户点击了广告技术平台 A、B、C 和 D 投放的广告。然后，用户安装了广告主的应用，该应用使用衡量广告技术合作伙伴 (MMP)。
  • 广告技术平台 A 将其来源重定向到 MMP。
  • 广告技术平台 B 和 C 不会重定向，但会共享其汇总键。
  • 广告技术平台 D 既不会重定向也不会共享汇总键。

MMP 注册广告技术平台 A 的来源，并定义了包含广告技术平台 B 和广告技术平台 D 的归因配置。

现在，MMP 的归因包括：

  • 广告技术平台 A，因为 MMP 注册了该广告技术平台重定向的来源。
  • 广告技术平台 B，因为广告技术平台 B 共享了键，而且 MMP 已将其纳入归因配置。

MMP 的归因不包括：

  • 广告技术平台 C，因为 MMP 未将其纳入归因配置。
  • 广告技术平台 D，因为它们既不会重定向也不会共享汇总键。

调试

为了支持调试以实现无重定向的跨广告网络归因，广告技术平台可在注册来源时设置额外的字段 shared_debug_key。如果在原始来源注册时设置了该字段，那么系统也会在触发器注册期间，在相应的派生来源上将此字段设为 debug_key，以便实现无重定向的跨广告网络归因。此调试键会作为 source_debug_key 附加在事件和汇总报告中。

在以下场景下，此调试功能仅适用于无重定向的跨广告网络归因：

  • 从应用到应用的衡量（广告 ID 获得允许）
  • 从应用到网站的衡量（广告 ID 获得允许，且在应用来源和网站触发器之间保持一致）
  • 从网站到网站的衡量（在同一浏览器应用中）；当来源和触发器上同时存在 ar_debug` 时

键发现（适用于无重定向的跨广告网络归因）

键发现旨在当一个或多个广告投放技术平台使用共享汇总键（如上面的无重定向的跨广告网络归因中所述）的情况下，简化广告技术平台（通常是 MMP）实现其归因配置的方式。

当 MMP 查询汇总服务以便为包含派生来源的广告系列生成摘要报告时，汇总服务要求 MMP 指定可能的键列表作为汇总作业的输入。在某些情况下，可能的来源汇总键的列表可能会很大或不明。可能的键数量太多会导致跟踪难度很大，并且处理起来也可能会很复杂且成本高昂。请参考以下示例：

  • 包含所有可能键的列表很大：
    • 广告投放网络正在执行复杂的用户获取计划，其中包括 20 个广告系列，每个广告系列包含 10 个广告组，每个广告组包含 5 个广告素材，这些广告素材每周都会按表现进行刷新。
  • 包含所有可能键的列表不明：
    • 广告投放网络会在许多移动应用中投放广告，但发布商应用 ID 的完整列表在广告系列发布时不明。
    • 广告客户会针对多个广告投放网络做工作，这些网络在来源注册时不会重定向至 MMP，但都各有不同的键结构和值，这些值可能不会事先与 MMP 共享。

随着键发现功能的推出：

  • 汇总服务不再需要可能的汇总键的完整枚举。
  • MMP 无需指定可能的键的完整列表，而是可以创建一个全空（或部分为空）的键集并设置阈值，以便输入中仅包括值超过阈值的（非预声明）的键。
  • MMP 会收到摘要报告，其中包含贡献值超过设定的阈值的键的噪声值。报告还可能包含没有相关真实用户贡献和纯粹为噪声的键。
  • MMP 在触发器注册中使用 x_network_bit_mapping 字段来确定哪个广告技术平台与哪个键对应。
  • 然后，MMP 可联系相应的广告投放技术平台，以了解来源键中的值。

总而言之，键发现可让 MMP 在无需事先知道汇总键的情况下获得这些键，并能够避免以增加噪声为代价处理大量的来源键。

菊链重定向

通过在来源或触发器注册 HTTPS 服务器响应中提供多个 Attribution-Reporting-Redirect 标头，广告技术平台可以使用 Attribution Reporting API 通过单次注册 API 调用执行多个来源和触发器注册。

在服务器响应中，广告技术平台还可以包含一个包含网址的 Location（302 重定向）标头，该标头会导致另一次注册，最多不超过设定的限制。

这两种标头都是可选的，如果不需要重定向，则可以不提供任何标头。您可以提供其中一种或两种类型的标头。如果网络连接失败，系统会重试来源和触发器注册请求（包括重定向）。每个请求的重试次数限制为一个固定值，以免对设备产生重大影响。

浏览器使用的 registerWebSource 和 registerWebTrigger 不接受重定向。如需了解详情，请参阅跨网站和应用实现指南。

在归因报告中查看衡量数据

Attribution Reporting API 支持以下类型的报告（本页的后文将对其进行更加详细的介绍）：

  • 事件级报告可将特定归因来源（点击或观看）与位数有限的高保真度触发器数据相关联。
  • 可汇总的报告不一定与特定归因来源相关联。与事件级报告相比，这些报告可提供更丰富、保真度更高的触发器数据，但这些数据只能以汇总形式提供。

这两种报告互为补充，可以同时使用。

事件级报告

将触发器归因于归因来源后，系统会生成事件级报告，并将其存储在设备上，直到可以在某个报告发送期（本页的后文将详细介绍）内将其发回到每个广告技术平台的回传网址。

如果只需极少量的触发器相关信息，事件级报告非常有用。对于点击，事件级触发器数据只能有 3 位，这意味着，可以为触发器指定 8 个类别中的一个。对于观看，事件级触发器数据只能有 1 位。此外，事件级报告不支持对高保真度触发器端数据（例如具体价格或触发时间）进行编码。由于归因是在设备上进行的，因此事件级报告中不支持跨设备分析。

事件级报告包含诸如以下数据：

  • 目标位置：表示触发器发生位置的广告主应用软件包名称或 eTLD+1
  • 归因来源 ID：注册归因来源时使用的归因来源 ID
  • 触发器类型：1 或 3 位低保真度触发器数据，具体取决于归因来源的类型

为所有报告应用的隐私保护机制

以下限制是在考虑了归因来源和触发器的优先级之后应用的。

广告技术平台数量限制

可通过 API 注册或接收报告的广告技术平台的数量有限制，当前方案如下：

  • 每 {来源应用、目标应用、30 天、设备} 100 个与归因来源相关联的广告技术平台。
  • 每 {来源应用、目标应用、30 天、设备} 10 个与归因触发器相关联的广告技术平台。
  • 20 个广告技术平台可以注册单个归因来源或触发器（通过 Attribution-Reporting-Redirect）

唯一目标数量限制

这些限制会查询大量应用以了解给定用户的应用使用行为，让一系列广告技术平台难以串通。

  • 对于所有已注册的来源，面向所有广告技术平台，该 API 每分钟对每个来源应用支持的唯一目标数量不超过 200 个。
  • 对于所有已注册的来源，面向单个广告技术平台，该 API 每分钟对每个来源应用支持的唯一目标数量不超过 50 个。此限制可防止一个广告技术平台用尽前面提到的速率限制中的全部预算。

已过期的来源不会计入速率限制。

每个来源应用每天有一个报告来源

对于给定的设备，给定广告技术平台在同一天或许只能使用一个报告来源在发布商应用中注册来源。此速率限制可防止广告技术平台使用多个报告来源来获取额外的隐私预算。

设想下列场景：单个广告技术平台想要使用多个报告来源为单个设备在一款发布商应用中注册多个来源。

  1. 广告技术平台 A 的报告来源 1 在应用 B 中注册一个来源
  2. 12 小时后，广告技术平台 A 的报告来源 2 尝试在应用 B 中注册一个来源

第二个来源（即广告技术平台 A 的报告来源 2）将会被该 API 拒绝。直到第二天，广告技术平台 A 的报告来源 2 才能在同一设备上的应用 B 中成功注册来源。

冷却期和速率限制

为了限制 {来源、目标} 对之间的用户身份泄露量，该 API 限制了用户在给定时间段内发送的总信息量。

当前方案对每个广告技术平台的限制为每 {来源应用、目标应用、30 天、设备} 100 个归因触发器。

唯一目标数量

该 API 对广告技术平台可尝试衡量的目标数量有限制。限值越低，广告技术平台就越难使用该 API 尝试衡量与展示的广告无关的用户浏览活动。

当前方案对每个广告技术平台的限制为每个来源应用 100 个具有未过期来源的不同目标。

为事件级报告应用的隐私保护机制

触发器数据的保真度有限

该 API 为浏览型转化触发器提供 1 位数据，为点击触发器提供 3 位数据。归因来源会继续支持完整的 64 位元数据。

您应评估是否以及如何减少触发器中表达的信息，以便能够通过事件级报告中有限的位数来表示。

差分隐私噪声框架

该 API 的目标是，通过使用 k-随机化响应为每个来源事件生成含噪声的输出，使事件级衡量满足本地差分隐私要求。

针对是否如实报告归因来源事件应用噪声。系统会在设备上注册一个归因来源，归因来源正常注册的概率为 $ 1-p $，并且设备从该 API 的所有可能输出状态（包括完全不报告任何内容，或提供多份虚假报告）中随机选择的概率为 $ p $。

如果满足以下等式，则 k-随机化响应就是一种 epsilon 差分隐私算法：

\[ p = \frac{k}{k + e^ε - 1} \]

如果 ε 的值较低，实际输出会受到 k-随机化响应机制的保护。我们还在对确切的噪声参数进行研究，并且可能会根据反馈进行更改，当前方案如下：

  • p=0.24%（对于导航来源）
  • p=0.00025%（对于事件来源）

可用触发器（转化）的限制

每个归因来源的触发器数量有限制，当前方案如下：

  • 1-2 个触发器，适用于广告观看归因来源（2 个触发器仅在安装后归因的情况下可用）
  • 3 个触发器，适用于广告点击归因来源

发送报告的具体时间范围（默认行为）

对于广告观看这种归因来源，事件级报告会在来源过期 1 小时后发送。您可以配置此过期时间，但它不能少于 1 天，也不能超过 30 天。如果两个触发器被归因于一个广告观看归因来源（通过安装后归因），则可以按如下所示的报告期间隔发送事件级报告。

广告点击这种归因来源的事件级报告无法配置，并且在来源不超过过期日期的指定时间点（相对于来源注册时间的时间点）发送。从归因来源注册到过期之间的时间会拆分为多个报告期。每个报告期都有一个截止时间（从归因来源注册时间算起）。在每个报告期结束时，设备都会收集自上一个报告期以来发生的所有触发器，并发送定期报告。该 API 支持以下报告期：

  • 2 天：设备会收集归因来源注册后最多 2 天内发生的所有触发器。报告会在归因来源注册 2 天零 1 小时后发送。
  • 7 天：设备会收集归因来源注册后 2 到 7 天内发生的所有触发器。 报告会在归因来源注册 7 天零 1 小时后发送。
  • 自定义时长，由归因来源的“expiry”属性定义。报告会在指定过期时间过去 1 小时后发送。此值不能少于 1 天，也不能超过 30 天。

灵活事件级配置

事件级报告的默认配置是指广告技术平台在开始进行实用性测试时建议开始使用的配置，但不一定适合所有使用情形。Attribution Reporting API 将支持更灵活的可选配置，以便广告技术平台可以更好地控制其事件级报告的结构，并能够最大限度地利用数据。

我们将分两个阶段向 Attribution Reporting API 中引入此额外的灵活性：

  • 第 1 阶段：精简版灵活事件级配置
    • 此版本提供了部分功能，这些功能可独立于第 2 阶段使用。
  • 第 2 阶段：完整版灵活事件级配置

第 1 阶段（精简版灵活事件级）可用于：

  • 通过指定报告期数，让报告的频率不同
  • 让每项来源注册的归因数量不同
  • 通过调低上述参数来减少总噪声
  • 配置报告期（而非使用默认值）

第 2 阶段（完整版灵活事件级）可用于执行第 1 阶段中的所有功能，以及：

  • 让报告中的触发器数据基数不同
  • 通过调低触发器数据基数来减少总噪声数

减少默认配置的一个维度可让广告技术平台增加另一个维度。或者，事件级报告中的总噪声数或许可通过净降低上述参数来减少。

除了根据广告技术平台所选配置动态设置噪声等级外，我们还制定了一些参数限制，以避免计算费用过高并带来输出状态过多（噪声会大量增加）的配置。以下是一组限制示例。欢迎您就 [设计方案][50]提供反馈：

  • 全局和每个 trigger_data 最多可以有共 20 个报告
  • 每个 trigger_data 最多可以有 5 个可能报告期
  • 最多可以有 32 个触发器数据基数（不适用于第 1 阶段：精简版灵活事件级）

请注意，随着广告技术平台开始使用此功能，使用极端值可能会导致大量噪声；如果未达到隐私保护级别，则可能导致注册失败。

可汇总的报告

在使用可汇总报告之前，您必须先设置自己的 Cloud 账号，然后开始接收可汇总报告。

与事件级报告相比，可汇总的报告可以更快地提供来自设备的触发器数据，并且保真度更高。这些保真度更高的数据只能以汇总方式获取，并且不会与特定触发器或用户相关联。汇总键最多可为 128 位，这使得可汇总的报告可以报告多种用例，例如：

  • 关于触发器值（如收入）的报告
  • 处理更多触发器类型

此外，可汇总报告使用与事件级报告相同的来源优先归因逻辑，但支持更多归因于点击或观看的转化。

关于 Attribution Reporting API 如何准备和发送可汇总报告的总体设计（如图所示）如下：

  1. 设备向广告技术平台发送加密的可汇总报告。在生产环境中，广告技术平台无法直接使用这类报告。
  2. 广告技术平台向汇总服务发送一批可汇总的报告以进行汇总。
  3. 汇总服务读取一批可汇总的报告，然后对其进行解密和汇总。
  4. 最终的汇总数据会以摘要报告的形式发回到广告技术平台。
Attribution Reporting API 准备和发送可汇总报告时遵循的流程。

可汇总的报告包含以下与归因来源相关的数据：

  • 目标位置：表示触发器出现位置的应用软件包名称或 eTLD+1 网址。
  • 日期：以归因来源表示的事件的发生日期。
  • 载荷：触发器值，以加密的键值对形式收集，在可信的汇总服务中用于计算汇总数据。

汇总服务

以下服务提供了数据汇总功能，并且有助于防范对汇总数据的未经授权的访问。

这些服务由不同的负责方（本页的后文将对其进行更加详细的介绍）进行管理：

  • 汇总服务是广告技术平台预计会部署的唯一服务。
  • 密钥管理和可汇总报告的会计核算服务由称为“协调方”的可信方运行。这些协调方负责验证运行汇总服务的代码是否为 Google 提供的公开代码，并验证所有汇总服务用户是否享受相同的密钥和可汇总报告会计核算服务。
汇总服务

广告技术平台必须提前部署基于 Google 提供的二进制文件的汇总服务。

该汇总服务在托管于云端的可信执行环境 (TEE) 中运行。TEE 具有以下安全优势：

  • 它可确保在 TEE 中运行的代码是由 Google 提供的特定二进制文件。除非满足此条件，否则汇总服务无法获取运行所需的解密密钥。
  • 它可为运行中的进程提供安全保障，使其免于被外部监控或篡改。

这些安全优势使得汇总服务可以更安全地执行敏感操作，例如访问加密数据。

如需详细了解汇总服务的设计、工作流程和安全注意事项，请参阅 GitHub 上的汇总服务文档。

密钥管理服务

这项服务负责验证汇总服务运行的是否为经过批准的二进制文件版本，如果是，则为广告技术平台中的汇总服务提供其触发器数据的正确解密密钥。

可汇总报告的会计核算

这项服务负责跟踪广告技术平台的汇总服务访问特定触发器（可以包含多个汇总键）的频率，并限制为仅可以访问适当数量的解密数据。如需了解详情，请参阅 Attribution Reporting API 汇总服务设计方案。

Aggregatable Reports API

用于为可汇总的报告创建贡献内容的 API 使用的基本 API 与为事件级报告注册归因来源时使用的基本 API 相同。以下部分介绍了该 API 的扩展。

注册可汇总的来源数据

当该 API 向归因来源 URI 发出请求时，广告技术平台可以使用 HTTP 标头 Attribution-Reporting-Register-Source 中名为 aggregation_keys 的新字段进行响应，借此注册一个名为 histogram_contributions 的汇总键列表，其中键名为 key_name，值为 key_piece：

  • (Key) Key name：键名的字符串。用作联接键，与触发器端键组合在一起后形成最终键。
  • (Value) Key piece：键的位串值。

最终直方图分区键在触发时通过对这些部分和触发器端部分执行二元 OR 运算进行完全定义。

最终键不得超过 128 位；如果键超过 128 位，就会被截断。这意味着 JSON 中的十六进制字符串不得超过 32 位。

详细了解汇总键的结构以及如何配置汇总键。

在下面的示例中，广告技术平台使用该 API 收集以下信息：

  • 在广告系列级汇总转化次数
  • 在地理位置级汇总购买价值
// This is where the Attribution-Reporting-Register-Source object appears when
// an ad tech registers an attribution source.

// Attribution source metadata specifying histogram contributions in aggregate report.
Attribution-Reporting-Register-Source:
…
aggregation_keys: {
  // Generates a "0x159" key piece named (low order bits of the key) for the key
  // named "campaignCounts".
  // User saw an ad from campaign 345 (out of 511).

  "campaignCounts": "0x159",
  // Generates a "0x5" key piece (low order bits of the key) for the key name "geoValue"
  // Source-side geo region = 5 (US), out of a possible ~100 regions.
  "geoValue": "0x5"
}

注册可汇总的触发器

触发器注册包括两个额外的字段。

第一个字段用于在触发器端注册一个汇总键列表。广告技术平台应使用 HTTP 标头 Attribution-Reporting-Register-Trigger 中的 aggregatable_trigger_data 进行响应。对于每个汇总键，该列表中都包含以下字段：

  • Key piece：键的位串值。
  • Source keys：一个字符串列表，其中包括归因来源端键的名称，触发器键应与这些键组合在一起以形成最终键。

第二个字段用于注册应对每个键有贡献的值的列表。广告技术平台应使用 HTTP 标头 Attribution-Reporting-Register-Trigger 中的 aggregatable_values 字段进行响应。第二个字段用于注册应对每个键有贡献的值的列表，这些值可以是 $ [1, 2^{16}] $ 范围内的整数。

每个触发器都可以对可汇总报告做出多项贡献。对任何指定来源事件的贡献总量受 $ L1 $ 参数制约，对于指定的来源，对所有汇总键的贡献（值）的总和不得超过该参数。$ L1 $ 是指每个来源事件的直方图贡献的 L1 灵敏度或范数。超过这些限制会导致未来的贡献悄然下降。初始方案是将 $ L1 $ 设为 $ 2^{16} $ (65536)。

汇总服务中的噪声会按照与此参数成一定比例进行缩放。因此，建议根据分配给指定汇总键的 $ L1 $ 预算部分，适当缩放为指定汇总键报告的值。该方法有助于确保，在应用了噪声时，汇总报告能够尽可能保持较高的保真度。这种机制非常灵活，可以支持多种汇总策略。

在以下示例中，通过在 campaignCounts 和 geoValue 之间分配 $ L1 $ 贡献，将在这两者之间平均分配隐私预算：

// This is where the Attribution-Reporting-Register-Trigger object appears
// when an ad tech registers a conversion trigger.

// Specify a list of dictionaries that generates aggregation keys.
Attribution-Reporting-Register-Trigger:{
    …
    "aggregatable_trigger_data":

    [
    // Each dictionary independently adds pieces to multiple source keys.
    {
    // Conversion type purchase = 2 at a 9-bit offset, i.e. 2 << 9.
    // A 9-bit offset is needed because there are 511 possible campaigns, which
    // will take up 9 bits in the resulting key.
        "key_piece": "0x400",// Conversion type purchase = 2
        // Apply this key piece to:
        "source_keys": ["campaignCounts"]
    },
    {
    // Purchase category shirts = 21 at a 7-bit offset, i.e. 21 << 7.
    // A 7-bit offset is needed because there are ~100 regions for the geo key,
    // which will take up 7 bits of space in the resulting key.
        "key_piece": "0xA80",
        // Apply this key piece to:
        "source_keys": ["geoValue", "nonMatchingIdsListedHereAreIgnored"]
    }
    ]

    // Specify an amount of an abstract value which can be integers in [1, 2^16] to
    // contribute to each key that is attached to aggregation keys in the order that
    // they're generated.
    aggregatable_values:
    {
    // Privacy budget for each key is L1 / 2 = 2^15 (32768).
    // Conversion count was 1.
    // Scale the count to use the full budget allocated: 1 * 32768 = 32768.
        "campaignCounts": 32768,

    // Purchase price was $52.
    // Purchase values for the app range from $1 to $1,024 (integers only).
    // Scaling factor applied is 32768 / 1024 = 32.
    // For $52 purchase, scale the value by 32 ($52 * 32 = $1,664).
        "geoValue": 1664
    }
}

上面的示例生成了以下直方图贡献：

[
  // campaignCounts:
  {
    "key": "0x559", // = 0x159 | 0x400
    "value": 32768
  },
  // geoValue:
  {
    "key": "0xA85",  // = 0x5 | 0xA80
    "value": 1664
  }
]

可以反转缩放比例以获得正确的值，即应用的模除噪声：

L1 = 65536
trueCampaignCounts = campaignCounts / (L1 / 2)
trueGeoValue = geoValue / (L1 / 2) * 1024

差分隐私

该 API 的一个目标是拥有一个可以支持差分隐私汇总衡量的框架。这可以通过添加与 $ L1 $ 预算成比例的噪声来实现，例如拾取具有以下分布的噪声：

\[ Laplace(\frac{L1}{ε}) \]

Protected Audience API 与 Attribution Reporting API 集成

通过跨 Protected Audience API 和 Attribution Reporting API 的跨 API 集成，广告技术平台可以评估其在各种再营销策略中的归因效果，从而了解哪些类型的受众群体带来的投资回报率最高。

通过这种跨 API 集成，广告技术平台可以：

  • 创建要同时用于 1) 互动报告和 2) 来源注册的 URI 的键值对映射。
  • 在来源端键映射中添加 CustomAudience，以便生成汇总摘要报告（使用 Attribution Reporting API）。

当用户查看或点击广告时：

  • 使用 Protected Audience 报告这些互动时所使用的网址还将用于通过 Attribution Reporting API 将查看或点击注册为符合条件的来源。
  • 广告技术平台可以选择使用该网址传递 CustomAudience（或其他有关广告的相关上下文信息，例如广告展示位置或查看时长），以便在广告技术平台正在查看广告系列的整体效果时，能够将此元数据向下传播到汇总报告中。

如需详细了解如何在 Protected Audience 中启用此功能，请参阅 Protected Audience API 说明文档的相关内容。

注册优先级、归因和报告示例

此示例展示了一组用户互动，以及广告技术平台定义的归因来源和触发器优先级对归因报告的影响。在此示例中，我们做出如下假设：

  • 所有归因来源和触发器都由同一个广告技术平台为同一广告主注册。
  • 所有归因来源和触发器都发生在第一个事件报告期内（在发布商应用中首次展示广告后的 2 天内）。

请考虑用户做出以下行为的情况：

  1. 用户看到一则广告。广告技术平台向该 API 注册归因来源，优先级为 0（观看 1）。
  2. 用户看到一则广告，广告技术平台注册归因来源，优先级为 0（观看 2）。
  3. 用户点击一则广告，广告技术平台注册归因来源，优先级为 1（点击 1）。
  4. 用户在广告主应用中完成转化（转到着陆页）。广告技术平台向 API 注册触发器，优先级为 0（转化 1）。
    • 触发器注册后，API 先归因，然后再生成报告。
    • 可用的归因来源有 3 个：观看 1、观看 2 和点击 1。API 将此触发器归因于点击 1，因为它优先级最高且最新。
    • 观看 1 和观看 2 被舍弃，并且不再符合参与后续归因的条件。
  5. 用户在广告主应用中将一件商品添加到购物车，广告技术平台注册触发器，优先级为 1（转化 2）。
    • 点击 1 是唯一符合条件的归因来源。API 将此触发器归因于点击 1。
  6. 用户在广告主应用中将一件商品添加到购物车，广告技术平台注册触发器，优先级为 1（转化 3）。
    • 点击 1 是唯一符合条件的归因来源。API 将此触发器归因于点击 1。
  7. 用户在广告主应用中将一件商品添加到购物车，广告技术平台注册触发器，优先级为 1（转化 4）。
    • 点击 1 是唯一符合条件的归因来源。API 将此触发器归因于点击 1。
  8. 用户在广告主应用中购买商品，广告技术平台注册触发器，优先级为 2（转化 5）。
    • 点击 1 是唯一符合条件的归因来源。API 将此触发器归因于点击 1。

事件级报告具有以下特征：

  • 默认情况下，系统会在适用的报告期后发送前 3 个归因于点击的触发器和第一个归因于观看的触发器。
  • 在报告期内，如果存在以更高优先级注册的触发器，这些触发器优先于最新的触发器并取而代之。
  • 在前面的示例中，广告技术平台在 2 天的报告期后收到 3 份事件报告，分别与转化 2、转化 3 和转化 5 相关。
    • 5 个触发器全都归因于点击 1。默认情况下，API 会发送前 3 个触发器的报告：转化 1、转化 2 和转化 3。
    • 但是，转化 4 的优先级 (1) 高于转化 1 的优先级 (0)。因此，转化 4 的事件报告取代了转化 1 的事件报告被发送出去。
    • 此外，转化 5 的优先级 (2) 高于所有其他触发器。因此，转化 5 的事件报告取代了转化 4 的报告被发送出去。

可汇总报告具有以下特征：

  • 加密的可汇总报告在处理后（注册触发器几小时后）会立即发送到广告技术平台。

    作为广告技术平台，您可以根据可汇总报告中的未加密信息创建批次。这些信息包含在可汇总报告的 shared_info 字段中，其中包括时间戳和报告来源。您不能根据汇总键值对中的任何加密信息分批发送报告，但可以采用一些简单的策略，例如每天或每周分批发送报告。理想情况下，一个批次应包含至少 100 份报告。

  • 何时以及如何将可汇总报告分批并发送到汇总服务由广告技术平台决定。

  • 与事件级报告相比，加密的可汇总报告可以将更多触发器归因于某一个来源。

  • 在前面的示例中，发送了 5 份可汇总报告，每个已注册的触发器各一份。

过渡调试报告

Attribution Reporting API 是一种相当复杂且无需跨应用标识符进行归因衡量的新方法。因此，我们支持一种过渡机制，以便在广告 ID 可用（用户没有选择停用会使用广告 ID 的个性化功能且发布商或广告主应用已声明广告 ID 相关权限）时了解归因报告的更多信息。这样可以确保该 API 在发布期间可以被完全理解，有助于消除任何 bug，并更加轻松地与基于广告 ID 的替代方案进行比较。调试报告分为两种：归因成功报告和详细报告。

如需详细了解如何根据“应用到网站”和“网站到应用”衡量结果来调试报告，请参阅过渡调试报告中的指南。

归因成功调试报告

来源注册和触发器注册都接受由广告技术平台填充的新 64 位 debug_key 字段（格式为字符串）。在事件级报告和汇总报告中，传入的 source_debug_key 和 trigger_debug_key 将保持不变。

如果创建同时包含来源和和触发器调试键的报告，则以有限的延迟时间向 .well-known/attribution-reporting/debug/report-event-attribution 端点发送调试报告副本。调试报告与普通报告相同，包括两个调试键字段。通过在这两个报告中包含这些键，可将常规报告关联到单独的调试报告流。

  • 对于事件级报告：
    • 调试报告副本会在有限时间内发送，因此不受可用触发器的限制约束，这让广告技术平台能够了解这些限制对事件级报告的影响。
    • 与错误触发器事件相关联的事件级报告将不包含 trigger_debug_key。这样一来，广告技术平台就可以更清楚地了解在 API 中应用噪声的方式。
  • 对于可汇总报告：
    • 只有在同时设置了 source_debug_key 和 trigger_debug_key 的情况下，我们才会支持包含解密载荷的新 debug_cleartext_payload 字段。

详细调试报告

借助详细调试报告，开发者可以监控归因来源或触发器注册中的某些故障问题。这些调试报告会在归因来源或触发器注册成功后，以有限的延迟时间向 well-known/attribution-reporting/debug/verbose 端点发送。

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

  • Type：导致生成报告的原因。请参阅详细报告类型的完整列表。
    • 一般而言，有来源详细报告和触发器详细报告。
    • 来源详细报告要求广告 ID 对发布商应用可用，而触发器详细报告要求广告 ID 对广告主应用可用。
    • 触发器的详细报告（trigger-no-matching-source 除外）可以选择包含 source_debug_key。仅当广告 ID 也对发布商应用可用时，才能包含此键。
  • Body：报告的正文，具体取决于其类型。

广告技术平台需要使用 Attribution-Reporting-Register_Source 和 Attribution-Reporting-Register-Trigger 标头中新的 debug_reporting 字典字段来选择接收详细调试报告。

  • 来源详细报告仅要求选择启用来源注册标头。
  • 触发器调试报告仅要求选择启用触发器注册标头。

如何使用调试报告

如果发生转化（根据您现有的衡量系统），并且收到该转化的调试报告，则表示触发器已成功注册。

对于每个调试归因报告，请检查您是否收到与两个调试键相匹配的常规归因报告。

多种原因可能会导致数据不一致。

运行正常：

  • 可保护隐私的 API 行为：
    • 用户达到了报告速率限制 - 这会导致该时间段内的所有后续报告都无法发送；或者来源因待处理目标限制而被移除。
    • 对于事件级报告：报告会受随机响应（噪声）影响，并被限制，或者您可能会收到随机报告。
    • 对于事件级报告：已达到 3 个（针对点击）或 1 个（针对数据视图）报告的限制，后续报告没有明确的优先级设置，或者优先级低于现有报告。
    • 已超出可汇总报告的贡献限制。
  • 广告技术平台定义的业务逻辑：
    • 通过过滤条件或优先级规则滤除触发器。
  • 时间延迟或与网络可用时的互动（例如，用户长时间关闭设备）。

意外原因：

  • 实施问题：
    • 来源标头配置错误。
    • 触发器标头配置错误。
    • 其他配置问题。
  • 设备或网络问题：
    • 因网络状况而发生故障。
    • 来源或触发器注册响应未到达客户端。
    • API bug。

未来的注意事项和待解决的问题

Attribution Reporting API 正在开发中。此外，我们还在探索未来可能会推出的功能，例如非最终点击归因模型和跨设备衡量用例。

此外，我们希望就以下几个问题向社区征求反馈：

  1. 是否具有需要 API 针对已验证安装发送报告的用例？这些报告会计入广告技术平台各自的速率限制。
  2. 您在将 InputEvent 从应用传递到广告技术平台以进行源代码注册时，是否遇到任何困难？
  3. 对于预加载的应用或重新安装的应用，是否有任何特殊的归因用例？