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

Attribution Reporting API 可针对在同一设备上发生的来源和触发器实现跨应用和网站归因。浏览器（例如 Chrome）可以将来源注册和触发注册都委托给 Attribution Reporting API for Android，而不是在浏览器中处理这些注册。 这样一来，Android 就可以在网站和应用中匹配来源和触发条件。

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

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

通过 Android OS 注册来源和触发器

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

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

• 对于仅限网站的广告系列，广告技术平台仍可使用 Chrome 的 Attribution Reporting API 注册来源和触发，也可选择将两者都委托给操作系统。对于仅限网站的广告系列，如果来源或触发器可能发生在 WebView 中，广告技术平台必须将来源注册和触发器注册都委托给操作系统。如需了解详情，请参阅有关 WebView 的部分。

• 广告技术平台应避免同时使用 Chrome 和 Android API 注册来源和触发器，以免生成重复的归因报告。

• 浏览器和操作系统的归因是分开进行的。如果来源在浏览器中注册，但触发器在操作系统中注册，则这两者无法匹配，反之亦然。

• 对于可能会导致应用或网站触发器的来源，强烈建议广告技术平台将网站来源和触发器注册委托给 Android Attribution Reporting API。

• 对于可能由基于应用的来源触发的触发器，广告技术平台可以选择将网站触发器注册委托给 Android Attribution Reporting API。

• 对于来源和触发都发生在应用中的广告系列，两者都需要通过操作系统 Attribution Reporting API 进行注册。

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

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

示例

用户正在自己喜爱的新闻应用中阅读文章。他们看到一则前往巴黎的特价机票广告，便兴奋地点击预订。在新闻应用中投放广告的广告技术平台会通过 Android Attribution Reporting API 注册点击来源。用户会被带到 Chrome 中的广告客户网页，并可以在该网页上完成转化。广告客户网站上的广告技术平台会检查操作系统级 API 是否可用，结果是可用。该广告技术平台会指示 Chrome 将注册委托给操作系统，而不是直接通过 Chrome 的 Attribution Reporting API 进行注册，从而注册转化触发。然后，操作系统级 Attribution Reporting API 能够匹配应用来源和网站触发器，并发送相关报告。

应用来源注册：

1. Daily News Android 应用中的广告技术平台 SDK 使用 registerSource() 注册点击

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

3. 广告技术平台服务器使用 Attribution-Reporting-Register-Source 标头进行响应，以完成来源注册

Web 触发器注册：

1. 广告技术平台在 Attribution Reporting API 中注册触发器并检查操作系统可用性

2. Web ARA 会返回有关支持的平台的信息

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

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

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

6. 广告技术平台将使用操作系统 API 完成触发器注册

7. 操作系统 ARA 将按照与应用<>应用归因相同的逻辑执行归因，并发送相同的报告

工作流程

以下步骤详细介绍了如何完成此任务：

1. 应用中的广告技术平台通过 Android 的 Attribution Reporting API 注册来源，并进行以下调整：

   • 若要注册预计会在网站上转化的应用来源，Attribution-Reporting-Register-Source 响应标头应包含网站目标位置 (eTLD+1)，而不是应用目标位置。

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

   • 部分广告客户可能正在使用多个衡量服务提供商（例如，第三方衡量工具或分析工具），并使用 302 重定向链。在某些情况下，Attribution Reporting API 会在后台跟踪 Attribution-Reporting-Redirect 标头中指定的重定向路径，同时在前景中执行 302 重定向路径以处理现有的导航请求。这些请求将发送到同一网址，可能会导致第三方衡量服务提供商重复统计注册。为防止重复计算注册次数，广告技术平台可以修改重定向行为，以将 Attribution Reporting API 注册发送到备选但确定的网址。

   • 如需启用此行为，广告技术平台需要在响应注册请求时添加新的 HTTP 标头：

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

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

   • 其余来源注册流程与标准的应用到应用来源注册相同。

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

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

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

     2. Attribution-Reporting-Support 请求标头由 Chrome 返回给广告技术平台。如果该 API 在 Chrome 浏览器和 Android 设备上均处于启用状态，则标头将返回 os, web

     Attribution-Reporting-Support: os, web
     

   • 然后，广告技术平台应使用 Attribution-Reporting-Register-OS-Trigger 标头告知 Chrome 委托给操作系统，该标头：

     1. 告知 Chrome 将注册委托给操作系统

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

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

     3. 操作系统 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 标头来设置首选平台以处理触发器注册。键为 preferred-platform，允许的值为 os 和 web。浏览器会在首选平台可用时使用该平台，并在操作系统不可用时回退到 Web 平台。

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

网站来源注册：

1. 广告技术平台在 Attribution Reporting API 中注册来源并检查操作系统可用性

2. Web ARA 会返回有关支持的平台的信息

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

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

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

6. 广告技术平台将使用操作系统 API 完成来源注册

应用触发器注册：

1. 服装商店 Android 应用中的广告技术 SDK 向操作系统 ARA 注册触发器

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

3. 广告技术服务器使用 Attribution-Reporting-Register-Trigger 标头进行响应，以完成触发器注册

4. 操作系统 ARA 将按照与应用<>应用归因相同的逻辑执行归因，并发送相同的报告

工作流程

以下步骤详细介绍了如何完成此任务：

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

   • 对于网站到应用的用例，在注册来源时，必须直接指定归因来源参数，方法是使用 attributionsrc 标记或使用 JavaScript 注册
   • 以下示例使用 attributionsrc 标记指定来源参数：

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

2. Attribution-Reporting-Support 请求标头由 Chrome 返回给广告技术平台。如果该 API 在 Chrome 浏览器和 Android 设备上均处于启用状态，则标头将返回 os, web。

   Attribution-Reporting-Support: os, web
   

3. 广告技术应使用 Attribution-Reporting-Register-OS-Source 标头告知 Chrome 委托给操作系统级 API，该标头：

   1. 告知 Chrome 将注册委托给操作系统
   2. Chrome 通过调用操作系统 API 函数 registerWebSource() 将注册委托给操作系统
   3. 对 registerWebSource() 的调用在后台进行，广告技术平台无需直接调用 registerWebSource()
   4. 操作系统 API 会向从浏览器传递的广告技术 URI 发起辅助 API 调用

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

   • 在某些情况下，Attribution-Reporting-Support 标头不可用。 发生这种情况时，广告技术平台仍可通过添加 Attribution-Reporting-Info 标头来设置首选平台以处理来源注册。键为 preferred-platform，允许的值为 os 和 web。浏览器会在首选平台可用时使用该平台，并在操作系统不可用时回退到 Web 平台。

   Attribution-Reporting-Info: preferred-platform=os
   

   • 为了完成来源注册，广告技术平台的端点应使用响应标头 Attribution-Reporting-Register-Source 响应 Android Attribution Reporting API 请求。响应还应在目的地字段中指定应用目的地。

   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 开发者应注意，操作系统 Attribution Reporting API 的 destination 字段应为应用软件包，而不是网址。

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

   • 下一部分（粗略报告）将说明使用双目的地可能会对报告中的噪声产生什么影响。

2. 对于双目的地来源，请使用粗略报告来减少事件级报告中的噪声：

   • 如果在来源注册中同时指定了操作系统（应用）和网站目标位置，事件级报告默认会指定触发器发生在网站目标位置还是应用目标位置。不过，为了保持隐私保护限度，系统会向这些报告添加额外的噪声。
   • 广告技术平台可以使用 Attribution-Reporting-Register-Source 标头下的 coarse_event_report_destinations 字段来启用粗略报告并减少噪声。如果指定了 coarse_event_report_destinations 字段的来源赢得归因，生成的报告将同时包含应用和网站目标位置，而不会区分触发器的实际出现位置，但与指定了应用或网站目标位置的报告相比，噪声更少。
   • 汇总报告保持不变。

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

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

1. 注册应用来源和 Custom Tab 触发器：

   • 按照说明注册应用来源和网站触发器。

2. 注册 Custom Tab 来源和应用触发器：

   • 按照说明注册网站来源和应用触发器。

3. 注册 CCT 来源和 CCT 触发器

   • 这与 Chrome 中的任何网站到网站的网页归因的处理方式相同。

对于使用 WebView 的应用

某些应用可能会使用 WebView 来显示内容。WebView 有多种使用情形，例如呈现广告、托管 Web 内容或提供更适合采用 Web 格式的自定义应用功能。

1. 为了允许 WebView 使用 Attribution Reporting API，需要为嵌入应用配置正确的权限。

2. WebView 中仅提供操作系统级归因。Attribution-Reporting-Support 标头将仅返回 os，并且仅在 Android Attribution Reporting API 可用时才返回。

3. 在委托给操作系统时，WebView 可能会使用 registerSource 或 registerWebSource 以及 registerTrigger 或 registerWebTrigger。WebView 使用的方法由呈现 WebView 的应用设置，并按 WebView 确定。

   • registerSource 和 registerWebSource 之间的区别在于哪个来源会被记录为发布商。使用 registerSource 时，应用会记录为发布商；使用 registerSource 的一个示例是显示使用 WebView 呈现的广告的发布商应用。使用 registerWebSource 时，WebView 中托管的网站会记录为发布商；使用 registerWebSource 的一个示例是托管 WebView 的应用，并且 WebView 呈现的网站正在展示广告。registerTrigger 和 registerWebTrigger 的行为类似。第 3 项中的图表详细说明了应用或 SDK 开发者在哪些不同场景下会希望将 API 配置为使用 registerSource 或 registerWebSource，以及 registerTrigger 或 registerWebTrigger。
   • 默认情况下，在调用 Android Attribution Reporting API 时，WebView 将使用 registerSource 和 registerWebTrigger。这会在触发器事件发生时将来源与应用相关联，并将触发器与 WebView 中网址的顶级来源相关联。

     • 如果应用需要其他行为，则需对 androidx.webkit.WebViewSettingsCompat 类使用新方法 setAttributionRegistrationBehavior。此方法将指定 WebView 是否应该调用 registerWebSource() 或 registerWebTrigger()，而不是调用 registerSource() 或 registerTrigger()。

     • 需要为每个已启动的 WebView 设置此行为。

     • 如果广告技术 SDK 正在启动 WebView，则该 SDK 需要设置此默认行为。

     • 如果应用希望使用 registerWebSource() 将来源注册与 WebView 中的网站（而非应用）相关联，则必须加入 WebApp 许可名单。如需加入许可名单，请填写此表单。该许可名单旨在缓解有关建立网站上下文信任的隐私疑虑。

     值	说明	用例示例
     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 中停用来源注册和触发器注册。

   1. 通过 WebView 进行的来源和触发器注册

   2. 广告技术平台应使用 Attribution-Reporting-Register-OS-Source 标头响应来源注册。根据为 WebView 设置的行为，这会使用操作系统调用 registerSource() 或 registerWebSource()，并从 Android Attribution Reporting API 向广告技术 URI 发起二次 API 调用。

      • 为了完成来源注册，广告技术平台的端点应使用响应标头来响应 Android Attribution Reporting API 请求。

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

   3. 其余来源注册保持不变。

   4. 广告技术平台应使用 Attribution-Reporting-Register-OS-Trigger 标头响应触发器注册。根据为 WebView 设置的行为，这会使用操作系统调用 registerTrigger() 或 registerWebTrigger()，并从 Rb 发起到广告技术平台 URI 的二次 API 调用。

   5. 为了完成触发注册，广告技术平台的端点应使用响应标头来响应 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"]}
       ],
       ...
   }
   

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

调试

在设置应用到网站实现时，建议设置调试报告，以验证来源和触发器是否已正确注册；如果未正确注册，则接收有关原因的信息。

如需了解常规的 Attribution Reporting 调试步骤，请参阅调试实用指南。