此页面由 Cloud Translation API 翻译。

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 能够将应用来源和网站触发器进行匹配，并发送相关报告

应用来源注册：

Daily News Android 应用中的广告技术 SDK 使用 registerSource()
Android 上的 Attribution Reporting API 向广告技术平台服务器发送请求提供给 registerSource() 的网址
广告技术平台服务器提供 Attribution-Reporting-Register-Source 响应标头以完成来源注册

Web 触发器注册：

广告技术平台注册触发器并检查 Attribution Reporting API
网络 ARA 会返回有关哪个平台受支持的信息
OS-Trigger 标头会指示 Web ARA API 调用 OS ARA API registerWebTrigger() 函数
registerWebTrigger() 的调用在后台进行，开发者无需直接通过操作系统调用 registerWebTrigger()
OS ARA 接管操作，并向由 Attribution-Reporting-Register-OS-Trigger 标头
广告技术平台将通过 OS API 完成触发器注册
OS ARA 会根据应用于应用归因，并发送相同的报告

工作流程

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

应用中的广告技术平台向 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 应用中展示原生广告，请参阅关于网页视图的部分
广告主网站上的广告技术平台通过询问来注册触发器 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 能够将网站来源和应用触发器进行匹配，发送相关报告

网站来源注册：

广告技术平台注册来源并检查 Attribution Reporting API
网络 ARA 会返回有关哪个平台受支持的信息
OS-Source 标头会指示 Web ARA API 调用 OS ARA API registerWebSource() 函数
registerWebSource() 的调用在后台进行，开发者无需直接通过操作系统调用 registerWebSource()
OS ARA 接管操作并向提供的广告技术平台服务器网址发送请求按 Attribution-Reporting-Register-OS-Source 标头
广告技术平台将通过 OS API 完成来源注册

应用触发器注册：

服装店 Android 应用中的广告技术 SDK 向 OS ARA
Android 上的 Attribution Reporting API 向广告技术平台服务器发送请求提供给 registerTrigger() 的网址
广告技术平台服务器返回 Attribution-Reporting-Register-Trigger 标头以完成触发器注册
OS ARA 会根据应用于应用归因，并发送相同的报告

工作流程

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

发布商网站上的广告技术平台会指示 Chrome 将注册委托给 Android Attribution Reporting API：
- 对于“网站到应用”用例，在注册来源时，必须直接指定来源参数，即使用 attributionsrc 标记或使用 JavaScript 注册创建
- 以下示例使用 attributionsrc 标记来指定 source 参数：
```
<img src="https://adtech.example/conversionpixel"
attributionsrc="https://adtech.example/register-source?purchase=12">
```
Chrome 会将 Attribution-Reporting-Support 请求标头返回给广告技术如果该 API 在 Chrome 浏览器和 Android 设备上都已启用，标头将返回 os, web。
```
"Attribution-Reporting-Support": "os, web"
```
注意：必须启用 Attribution Reporting API 来成功跨应用和网站进行衡量。
广告技术平台应使用 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。
- 来源注册的其余部分保持不变。
广告主应用中的广告技术平台向 Android 注册触发器 Attribution Reporting API：
- 对于应用中发生的触发器，应用使用 Android Attribution Reporting API。

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

设置双目标目的地
- 有些广告系列可能设置为在广告客户的应用中或取决于各种因素，例如用户是否安装了该应用
- 在这些情况下，建议将来源注册委托给操作系统（如果有），以便系统对来源进行正确归因，触发器的发生位置向操作系统注册源代码时，应用和网站目标位置可在相应的参数中指定。
- 应用目标位置应在 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"
    ...
}
```
- 下一节中粗略报告将介绍如何使用双重目标页面可能会影响报告中的噪声。
使用粗略报告来减少事件级报告中的噪声，目标来源：
- 如果来源中同时指定了操作系统（应用）和网站目标位置事件级报告将指明该触发器是否发生默认存储在网站目标位置或应用目标位置不过，为了维护隐私限制，因此这些报告中会增加额外的噪声。
- 广告技术平台可以使用coarse_event_report_destinations Attribution-Reporting-Register-Source标头，用于启用粗略报告功能并减少噪声。如果具有 coarse_event_report_destinations 的来源字段赢得归因，生成的报告会同时包含应用和网站目标位置，而不区分实际触发器的位置但其噪声低于应用或网站目标位置的报告。
- 汇总报告保持不变。

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

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

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

对于使用 WebView 的应用

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

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

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

默认情况下，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 注册的来源和触发器。

来自 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",
    ...
}
```
- 来源注册的其余部分保持不变。
广告技术平台应使用 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 调试步骤，请参阅调试实战宝典。