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
      
    • 来源注册流程的其余部分与 应用到应用的来源注册

  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 标头。密钥是首选平台, 允许的值为 osweb。浏览器将使用首选平台 当操作系统可用时,会回退到 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 能够将网站来源和应用触发器进行匹配, 发送相关报告

<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
    
  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,允许的值为 osweb。通过 浏览器会使用首选平台(如果可用),并回退到 在操作系统不可用时启动 Web 平台。
    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">
  2. 注册自定义标签页来源和应用触发器: <ph type="x-smartling-placeholder">
  3. 注册 CCT 来源和 CCT 触发器 <ph type="x-smartling-placeholder">

对于使用 WebView 的应用

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

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

  2. 委托给操作系统时,WebView 可能会使用 registerSourceregisterWebSourceregisterTriggerregisterWebTrigger。有哪些方法 由呈现 WebView 的应用设置,由 每个 WebView

    • registerSourceregisterWebSource 之间的区别在于 该来源会被记录为发布商。使用 registerSource 时,系统会记录应用 ;使用 registerSource 的示例如下: 发布商应用。包含 registerWebSource 时,系统会将 WebView 中托管的网站记录为 发布商;下面举例说明了在什么情况下使用 registerWebSource 的应用 托管 WebView 的网站,而由 WebView 呈现的网站 展示广告。registerTriggerregisterWebTrigger 的行为类似。通过 第 3 项中的图表详细说明了应用或 SDK 开发者 您希望将该 API 配置为使用 registerSourceregisterWebSource, 和 registerTriggerregisterWebTrigger
  3. 默认情况下,WebView 在以下情况下将使用 registerSourceregisterWebTrigger: 调用 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 调试步骤,请参阅调试实战宝典