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

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

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

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

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

只有当同一设备上的浏览器和 Android OS 中都启用了 Attribution Reporting API 时，才能实现跨应用和跨网站归因。Android Attribution Reporting API 的可用性通过 Attribution-Reporting-Support 标头发送。此标头将返回“os”或“web”，或同时返回这两者，具体取决于相应设备上可用的选项。如果这两者都适用，广告技术平台可以选择向浏览器或操作系统注册网站来源和网站触发器。

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

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

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

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

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

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

• 对于来源和触发器都发生在应用中的广告系列，需要使用 OS 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 标头进行响应，以完成来源注册

网站触发器注册：

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

2. Web 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 的 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. Chrome 会将 Attribution-Reporting-Support 请求标头返回给广告技术平台。如果 Chrome 浏览器和 Android 设备上都启用了该 API，则标头将返回 os, web

     Attribution-Reporting-Support: os, web
     

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

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

     2. Chrome 通过调用操作系统 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 标头来设置首选平台来处理触发器注册。键为 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. 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 标记指定来源参数：

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

2. Chrome 会将 Attribution-Reporting-Support 请求标头返回给广告技术平台。如果 Chrome 浏览器和 Android 设备上都启用了该 API，该标头将返回 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. OS 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 请求。响应还应在 destination 字段中指定应用目的地。

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

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

   • 下一部分将介绍粗略报告，并说明使用双目的地可能会如何影响报告中的噪声。

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

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

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

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

1. 注册应用来源和自定义标签页触发器：

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

2. 注册自定义标签页来源和应用触发器：

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

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

   • 这与 Chrome 中的任何网站到网站的网站归因一样。

对于使用 WebView 的应用

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

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

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

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 的不同场景。
   • 默认情况下，WebView 在调用 Android Attribution Reporting API 时将使用 registerSource 和 registerWebTrigger。这会在触发器事件发生时将来源与应用相关联，并将触发器与 WebView 中网址的顶级来源相关联。

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

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

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

     • 如果应用希望使用 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"]}
       ],
       ...
   }
   

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

调试

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

如需了解归因报告的常规调试步骤，请参阅调试手册。