Attribution Reporting API 跨网站和应用实现指南

Attribution Reporting API 支持对来源进行跨应用和跨网站归因。 发生在同一设备上。Chrome 等浏览器 可以将来源注册和触发器注册委托给归因报告 API for Android，而不是在浏览器中处理这些注册。 这样，Android 就能跨网站和应用匹配来源和触发器。

本指南将为您介绍如何设置跨应用和跨网站归因。

在设置跨应用和跨网站归因时，强烈建议您也 熟悉可用的调试解决方案，以确保 设置是否按预期运行。

在 Android OS 中注册来源和触发器

只有在使用归因工具时，跨应用和跨网站归因才可用 在同一设备上的浏览器和 Android OS 中均启用 Reporting API 设备。发送 Android Attribution Reporting API 的可用性 通过 Attribution-Reporting-Support 标头进行设置。此标头将返回操作系统 或同时在网页上，具体取决于该设备上的功能。如果两者都 广告技术平台将可以选择注册网站来源和网站 与浏览器或操作系统相关联。

广告技术平台需要决定是注册网站来源还是网站触发器 浏览器或操作系统。

• 对于仅适用于网站的广告系列，广告技术平台仍可以同时注册来源和触发器 或者选择将这两者委托给操作系统。 对于来源或触发器可能发生在 WebView，广告技术平台必须将来源注册和触发器注册委托给 操作系统如需了解详情，请参阅 WebView 部分。
• 广告技术平台应避免向 Chrome 注册来源和触发器 和 Android API，以免重复归因 报告。
• 浏览器和操作系统的归因是分开进行的。如果来源是 但触发器已在操作系统中注册，那么这两个 反之亦然。
• 对于可能促成应用或网站触发器的来源，强烈建议 建议广告技术平台将网站来源和触发器注册委托给 Android Attribution Reporting API。
• 对于可能由基于应用的来源促成的触发器，广告技术平台可以 选择将网站触发器注册委托给 Android Attribution Reporting API。
• 对于来源和触发器都发生在应用内的广告系列，两者都会发生 需要使用 OS Attribution Reporting API 进行注册。

注册应用来源和网站触发器

对于某些广告系列，来源可能会在触发器发生时出现在应用中 在同一设备上的移动浏览器中访问网站。

示例

一位用户在喜爱的新闻应用中阅读文章。他们看到了便宜的广告 并迫不及待地点击预订了。在 新闻应用通过 Android Attribution Reporting API 注册点击来源。 用户会转到 Chrome 中广告客户的网页，并在其中 转化。广告客户网站上的广告技术平台会检查操作系统级 API 是否 是的。广告技术平台会按以下方式注册转化触发器： 指示 Chrome 将注册委托给操作系统，而不是注册 。操作系统级归因 然后，Reporting API 能够将应用来源和网站触发器进行匹配，并发送 相关报告

<ph type="x-smartling-placeholder">

</ph>

应用到网站的归因流程

应用来源注册：

1. Daily News Android 应用中的广告技术 SDK 使用 registerSource()

2. Android 上的 Attribution Reporting API 向广告技术平台服务器发送请求 提供给 registerSource() 的网址

3. 广告技术平台服务器提供 Attribution-Reporting-Register-Source 响应 标头以完成来源注册

Web 触发器注册：

1. 广告技术平台注册触发器并检查 Attribution Reporting API

2. 网络 ARA 会返回有关哪个平台受支持的信息

3. OS-Trigger 标头会指示 Web ARA API 调用 OS ARA API registerWebTrigger() 函数

4. registerWebTrigger() 的调用在后台进行，开发者 无需直接通过操作系统调用 registerWebTrigger()

5. OS ARA 接管操作，并向由 Attribution-Reporting-Register-OS-Trigger 标头

6. 广告技术平台将通过 OS API 完成触发器注册

7. OS ARA 会根据应用于 应用归因，并发送相同的报告

工作流程

以下步骤进一步说明了如何完成该任务：

1. 应用中的广告技术平台向 Android 的归因工具注册来源 Reporting API 进行了以下调整：

   • 要注册预计会在网站上完成转化的应用来源， Attribution-Reporting-Register-Source 响应标头应包含一个网页 而不是应用目标。
   。

   Attribution-Reporting-Register-Source: {
       "web_destination": "https://advertiser.example",
       ...
   }
   

   注意： 适用于可能在网站 或应用目的地，请参阅双目的地部分
   • 有些广告主可能会使用多个衡量服务提供商（例如， 第三方衡量工具或分析工具）使用 302 重定向链。 在某些情况下，Attribution Reporting API 将遵循重定向路径 （在 Attribution-Reporting-Redirect 标头中指定） 同时针对现有 导航请求。这些请求会转到同一个网址，可能会导致 第三方衡量服务提供商对注册进行双重统计。接收者 防止重复统计注册，广告技术平台可以修改重定向行为 将 Attribution Reporting API 注册发送到备选 确定性网址。

   • 为了实现此行为，广告技术平台需要在出现以下情况时添加新的 HTTP 标头： 响应注册请求：

     • 标题为 Attribution-Reporting-Redirect-Config
     • 标头的值应为 redirect-302-to-well-known
     。

     Attribution-Reporting-Redirect-Config: redirect-302-to-well-known
     

     注意： 此标头之后的所有后续重定向 会在重定向 URI 路径开头附加 .well-known。

   • 来源注册流程的其余部分与 应用到应用的来源注册。

   。
   注意： 如果您或发布应用使用的是 WebView 要在 Android 应用中展示原生广告，请参阅关于网页视图的部分

2. 广告主网站上的广告技术平台通过询问来注册触发器 Chrome 将注册委托给 Android Attribution Reporting API：

   • 用户在网站上完成转化后，广告技术平台会 向 Chrome 注册触发器的请求

     1. 像素或 fetch() 请求可用于发出注册 触发器

     2. Chrome 会返回 Attribution-Reporting-Support 请求标头 技术如果 Chrome 浏览器和 Android 设备，标头将返回 os, web

     Attribution-Reporting-Support: os, web
     

   • 然后，广告技术平台应使用 Attribution-Reporting-Register-OS-Trigger 标头，以便：

     1. 指示 Chrome 将注册委托给操作系统

     2. Chrome 通过调用 OS API 函数将注册委托给操作系统 registerWebTrigger()

        • registerWebTrigger() 的调用在后台进行，广告技术平台 无需直接调用 registerWebTrigger()

     3. OS API 对传递的广告技术平台 URI 发起二次 API 调用 通过浏览器

     Attribution-Reporting-Register-OS-Trigger: "https://adtech.example/register-trigger",
     "https://other-adtech.example/register-trigger"
     

   • 在某些情况下，Attribution-Reporting-Support 标头不可用， 无法发送。在这种情况下，广告技术平台仍可以设置 处理触发器注册，方法是添加 Attribution-Reporting-Info 标头。密钥是首选平台， 允许的值为 os 和 web。浏览器将使用首选平台 当操作系统可用时，会回退到 Web 平台 不可用。

   。
   注意： Attribution-Reporting-Register-Trigger 标头，该标头包含网络注册信息和 包含操作系统注册的 Attribution-Reporting-Register-OS-Trigger 标头 应在指定首选平台时返回相关信息，以确保 可以进行平台注册操作系统注册和网站注册都必须 以便在首选平台不可用时 是否具有后备方法所需的参数。

   Attribution-Reporting-Info: preferred-platform=os
   

   • 如需完成触发器注册，广告技术平台的端点应做出响应 发送到 Android Attribution Reporting API 请求。

   Attribution-Reporting-Register-Trigger: {
       "event_trigger_data": [{"trigger_data":"1"}],
       "aggregatable_trigger_data": [
           {"key_piece":"0x400","source_keys":["campaignCounts"]},
           {"key_piece":"0xA80","source_keys":["geoValue"]}
       ],
       ...
   }
   

   • 触发器注册的其余部分保持不变。

注册网站来源和应用触发器

对于某些广告系列，来源可能发生在使用移动浏览器的网站上， 触发器触发。

示例

一位用户在 Android 手机上使用 Chrome 浏览器浏览某个网站。 他们看到了自己最喜欢的某家商店投放的某件毛衣的广告。点击 并跳转到之前已下载的应用该网站上的广告技术平台 投放广告的网站通过指示 Chrome 注册点击来源 将注册委托给 Android Attribution Reporting API，而不是 在 Chrome 上使用 Attribution Reporting API。用户购买这件毛衣 购物应用然后，广告主应用中的广告技术平台会注册 和 Android Attribution Reporting API 搭配使用转化触发器。操作系统级别 Attribution Reporting API 能够将网站来源和应用触发器进行匹配， 发送相关报告

<ph type="x-smartling-placeholder">

</ph>

从网站到应用的归因流程

网站来源注册：

1. 广告技术平台注册来源并检查 Attribution Reporting API

2. 网络 ARA 会返回有关哪个平台受支持的信息

3. OS-Source 标头会指示 Web ARA API 调用 OS ARA API registerWebSource() 函数

4. registerWebSource() 的调用在后台进行，开发者 无需直接通过操作系统调用 registerWebSource()

5. OS ARA 接管操作并向提供的广告技术平台服务器网址发送请求 按 Attribution-Reporting-Register-OS-Source 标头

6. 广告技术平台将通过 OS API 完成来源注册

应用触发器注册：

1. 服装店 Android 应用中的广告技术 SDK 向 OS ARA

2. Android 上的 Attribution Reporting API 向广告技术平台服务器发送请求 提供给 registerTrigger() 的网址

3. 广告技术平台服务器返回 Attribution-Reporting-Register-Trigger 标头以完成触发器注册

4. OS ARA 会根据应用于 应用归因，并发送相同的报告

工作流程

以下步骤进一步说明了如何完成该任务：

1. 发布商网站上的广告技术平台会指示 Chrome 将注册委托给 Android Attribution Reporting API：

   • 对于“网站到应用”用例，在注册来源时， 必须直接指定来源参数，即使用 attributionsrc 标记或使用 JavaScript 注册创建
   • 以下示例使用 attributionsrc 标记来指定 source 参数：

   <img src="https://adtech.example/conversionpixel"
   attributionsrc="https://adtech.example/register-source?purchase=12">
   

2. Chrome 会将 Attribution-Reporting-Support 请求标头返回给 广告技术如果该 API 在 Chrome 浏览器和 Android 设备上都已启用， 标头将返回 os, web。

   Attribution-Reporting-Support: os, web
   

   注意： 必须启用 Attribution Reporting API 来成功跨应用和网站进行衡量。

3. 广告技术平台应使用 Attribution-Reporting-Register-OS-Source 标头，以便：

   1. 指示 Chrome 将注册委托给操作系统
   2. Chrome 通过调用 OS API 函数将注册委托给操作系统 registerWebSource()
   3. registerWebSource() 的调用在后台进行，广告技术平台 无需直接调用 registerWebSource()
   4. OS API 对从 浏览器

   Attribution-Reporting-Register-OS-Source: "https://adtech.example/register-source"
   

   • 在某些情况下，Attribution-Reporting-Support 标头不可用。 在这种情况下，广告技术平台仍可以设置首选平台来处理 通过添加 Attribution-Reporting-Info 标头来注册来源注册。 键为 Preferred-platform，允许的值为 os 和 web。通过 浏览器会使用首选平台（如果可用），并回退到 在操作系统不可用时启动 Web 平台。
   。
   注意： Attribution-Reporting-Register-Source 标头，其中包含网络注册信息和 包含操作系统注册的 Attribution-Reporting-Register-OS-Source 标头 应在指定首选平台时返回相关信息，以确保 可以进行平台注册操作系统注册和网站注册都必须 以便在首选平台不可用时 是否具有后备方法所需的参数。

   Attribution-Reporting-Info: preferred-platform=os
   

   • 如需完成来源注册，广告技术平台的端点应做出响应 与响应标头相关联的 Android Attribution Reporting API 请求 Attribution-Reporting-Register-Source。响应还应该指定 应用目标位置。

   Attribution-Reporting-Register-Source: {
       "source_event_id":"123001",
       "destination":"android-app://com.example.advertiser",
       ...
   }
   

   • 为支持来源注册重定向，Chrome 将遵循 重定向并为每个重定向跃点调用网站上下文 API。
   • 来源注册的其余部分保持不变。

4. 广告主应用中的广告技术平台向 Android 注册触发器 Attribution Reporting API：

   • 对于应用中发生的触发器，应用使用 Android Attribution Reporting API。

同时具有应用和网站潜在目标位置的广告系列

1. 设置双目标目的地

   • 有些广告系列可能设置为在广告客户的应用中或 取决于各种因素，例如用户 是否安装了该应用
   • 在这些情况下，建议将来源注册委托给 操作系统（如果有），以便系统对来源进行正确归因， 触发器的发生位置向操作系统注册源代码时， 应用和网站目标位置可在相应的参数中指定。
   • 应用目标位置应在 destination 字段中
   • 网站目标位置应在 web_destination 字段中
   • Chrome 开发者应注意，操作系统的 destination 字段 Attribution Reporting API 应该是应用软件包，而不是网址。

   Attribution-Reporting-Register-Source: {
       "source_event_id":"123001",
       "destination":"android-app://com.example.advertiser",
       "web_destination": "https://example.advertiser"
       ...
   }
   

   • 下一节中粗略报告将介绍如何使用双重目标页面 可能会影响报告中的噪声。

2. 使用粗略报告来减少事件级报告中的噪声， 目标来源：

   • 如果来源中同时指定了操作系统（应用）和网站目标位置 事件级报告将指明该触发器是否发生 默认存储在网站目标位置或应用目标位置不过，为了维护 隐私限制，因此这些报告中会增加额外的噪声。
   • 广告技术平台可以使用coarse_event_report_destinations Attribution-Reporting-Register-Source标头，用于启用粗略报告功能 并减少噪声。如果具有 coarse_event_report_destinations 的来源 字段赢得归因，生成的报告会同时包含应用 和网站目标位置，而不区分实际触发器的位置 但其噪声低于应用或网站目标位置的报告 。
   • 汇总报告保持不变。

对于使用 Chrome 自定义标签页的应用

某些应用可能会使用自定义标签页来呈现网页内容。自定义标签页的行为 跨应用和移动网站进行衡量时，使用方式与常规网页类似。

1. 注册应用来源和自定义标签触发器： <ph type="x-smartling-placeholder">
   </ph>
   • 按照说明注册应用来源和网站触发器。
2. 注册自定义标签页来源和应用触发器： <ph type="x-smartling-placeholder">
   </ph>
   • 按照说明注册网站来源和应用触发器。
3. 注册 CCT 来源和 CCT 触发器 <ph type="x-smartling-placeholder">
   </ph>
   • 这与 Chrome 中的网站到网站归因的处理方式相同。

对于使用 WebView 的应用

某些应用可能会使用 WebView 显示内容。应用场景多种多样 例如呈现广告、托管 Web 内容或自定义应用 更适合网页格式的功能

1. WebView 中仅支持操作系统级归因。通过 Attribution-Reporting-Support 标头将仅返回操作系统，并且只有在 Android Attribution Reporting API 现已推出。

   注意 ：如需跨 Chrome 和 WebView 进行归因，请执行以下操作： Chrome 中的来源注册和触发器注册需要委托给操作系统 因为 WebView 仅支持基于操作系统的归因。

2. 委托给操作系统时，WebView 可能会使用 registerSource 或 registerWebSource 和 registerTrigger 或 registerWebTrigger。有哪些方法 由呈现 WebView 的应用设置，由 每个 WebView

   • registerSource 和 registerWebSource 之间的区别在于 该来源会被记录为发布商。使用 registerSource 时，系统会记录应用 ；使用 registerSource 的示例如下： 发布商应用。包含 registerWebSource 时，系统会将 WebView 中托管的网站记录为 发布商；下面举例说明了在什么情况下使用 registerWebSource 的应用 托管 WebView 的网站，而由 WebView 呈现的网站 展示广告。registerTrigger 和 registerWebTrigger 的行为类似。通过 第 3 项中的图表详细说明了应用或 SDK 开发者 您希望将该 API 配置为使用 registerSource 或 registerWebSource， 和 registerTrigger 或 registerWebTrigger。

3. 默认情况下，WebView 在以下情况下将使用 registerSource 和 registerWebTrigger： 调用 Android Attribution Reporting API。这会将来源与 应用，并在发生以下情况时，使用 WebView 中网址的顶级来源进行触发： 触发。

   • 如果应用需要其他行为，则需使用新方法 androidx.webkit.WebViewSettingsCompat 中的 setAttributionRegistrationBehavior 类。此方法将指定 WebView 是否应调用 registerWebSource() 或 registerWebTrigger()，而不是 registerSource() 或 registerTrigger()。
     • 需要为启动的每个 WebView 设置此行为。
     • 如果广告技术平台 SDK 正在启动 WebView，则 SDK 需要设置 这一默认行为
     • 对于想要使用 registerWebSource() 关联来源的应用 在 WebView 中向网站注册，而不是向应用注册，则必须 加入 WebApp 许可名单。如需加入许可名单，请填写此表单。通过 列入许可名单的目的是缓解 建立信任。
   • setAttributionRegistrationBehavior 的选项

   值	说明	使用场景示例
   APP_SOURCE_AND_WEB_TRIGGER（默认）	允许应用通过 WebView 注册应用来源（与应用软件包名称相关联的来源）和网站触发器（与 eTLD+1 相关联的触发器）。	使用 WebView（而非通过启用网络浏览）投放广告的应用
   WEB_SOURCE_AND_WEB_TRIGGER	允许应用通过 WebView 注册网站来源和网站触发器。	基于 WebView 的浏览器应用，其中广告展示和转化可能都发生在 WebView 中的网站上。
   APP_SOURCE_AND_APP_TRIGGER	允许应用通过 WebView 注册应用来源和应用触发器。	基于 WebView 的应用，其中广告展示和转化应始终与应用（而非 WebView 的 eTLD+1）相关联。
   已停用	停用通过 WebView 注册的来源和触发器。

4. 来自 WebView 的来源和触发器注册

   • 广告技术平台应使用 Attribution-Reporting-Register-OS-Source 标头。根据设置行为 对于 WebView，它会调用 registerSource() 或 registerWebSource() 以及从 Android 归因工具发起二次 API 调用 Reporting API 发送到广告技术平台 URI。

     • 如需完成来源注册，广告技术平台的端点应 使用 响应标头。

     Attribution-Reporting-Register-OS-Source: {
         "source_event_id":"123001",
         "destination":"android-app://com.example.advertiser",
         ...
     }
     

   • 来源注册的其余部分保持不变。

5. 广告技术平台应使用 Attribution-Reporting-Register-OS-Trigger 标头。根据设置行为 对于 WebView，它会调用 registerTrigger() 或 registerWebTrigger() 并发起从 Rb 对广告技术平台 URI 的二次 API 调用。

   • 如需完成触发器注册，广告技术平台的端点应 使用响应来响应 Android Attribution Reporting API 请求 标头。

   Attribution-Reporting-Register-OS-Trigger: {
       "event_trigger_data": [{"trigger_data":"1"}],
       "aggregatable_trigger_data": [
           {"key_piece":"0x400","source_keys":["campaignCounts"]},
           {"key_piece":"0xA80","source_keys":["geoValue"]}
       ],
       ...
   }
   

   • 触发器注册流程的其余部分保持不变。

调试

设置应用到 Web 的实现时，建议设置调试 报告，以验证来源和触发器是否注册正确，以及 未注册，以接收相关信息。

如需了解常规的 Attribution Reporting 调试步骤，请参阅调试实战宝典。