归因报告:跨应用和跨网站衡量

提供反馈

近期更新

Attribution Reporting API 设计方案所述,该 API 支持在一部 Android 赋能的设备上对以下触发器路径进行归因:

  • 从应用到应用:用户在某个应用中看到广告,然后在该应用或已安装的其他应用中完成转化。
  • 从应用到网站:用户在某个应用中看到广告,然后在移动浏览器或应用浏览器中完成转化。
  • 从网站到应用:用户在某个移动浏览器或应用浏览器中看到广告,然后在应用中完成转化。
  • 从网站到网站:用户在某个移动浏览器或应用浏览器中看到广告,然后在同一设备上的同一浏览器或其他浏览器中完成转化。

此处的“网站”是指应用中显示的 Web 内容。Web 内容可以显示在移动浏览器应用的上下文中,也可以作为嵌入式网站显示在非浏览器应用中。

上述触发器路径可转换为以下要求:

  • 对于广告技术平台:更新 API 调用和报告以支持应用到网站路径
  • 对于应用和浏览器:可将网站归因来源和网站触发器的注册传递给 Android

本文档介绍了如何扩展 Attribution Reporting API 以支持应用到网站、网站到应用和网站到网站触发器路径。此外,本文档还将介绍广告技术平台和应用需要做出哪些更改才能满足支持这些触发器路径的要求。

获取对 Attribution Reporting API 的访问权限

广告技术平台需要注册才能访问 Attribution Reporting API。如需了解详情,请参阅注册 Privacy Sandbox 账号

注册流程最终确定后,如果收到未注册的注册调用,则 API 将舍弃注册。

在注册时,广告技术平台应确保将所有可能用于跨应用和跨网站注册归因来源和触发器的服务器网址纳入到注册流程中。系统支持多个服务器注册网址,但仅支持一个报告来源。此报告来源来自其中一个服务器注册网址的网域。

针对广告技术平台的变更

针对注册和归因的变更

注册归因来源时,广告技术平台目前会指定一个目标位置字段,即发生触发器事件的应用软件包的名称。为了实现应用到网站衡量,我们计划支持一个应用目标位置字段(应用软件包名称)和一个网站目标位置字段 (eTLD+1)。

注册网站归因来源或触发器时,API 不支持重定向,因为每个托管网站内容的应用都可以拥有自己的权限模型。每个应用负责跟踪重定向(如果支持),并为每个重定向跳转调用网站上下文 API

此外,这种集成可让广告技术平台在网站归因来源中使用应用专有归因逻辑。例如,您现在可以在网站归因来源中指定安装后归因回溯期。

接收应用和网站报告

Android Attribution Reporting API 可以发送针对应用转化和网站转化的报告。如果广告技术平台不希望跨网站和应用途径保持一致的触发器数据和汇总键值对,则可以使用以下报告来区分网站转化和应用转化:

  • 对于事件级报告,我们将支持通过一个目标位置字段来指定触发器发生在网站上(目标位置为 eTLD+1)还是发生在应用上(目标位置为应用软件包名称)
  • 对于可聚合报告,目标位置将以明文形式发送。

网站到网站衡量的影响

应用会选择何时将注册传递给 Attribution Reporting API。下面是一些注意事项:

  • Attribution Reporting API 是否可以在该设备上使用?我们将向应用公开一个新信号,它将返回该设备上是否可以使用 Attribution Reporting API 的信息。请参阅“应用变更”部分,详细了解应用如何将注册传递给 Attribution Reporting API。
  • 应将归因来源和触发器的哪个部分传递给 API?这将由每个应用或广告技术平台(如果应用允许)决定。如果应用有自己的效果衡量解决方案,可以考虑改用该解决方案。最后,将所有来源和触发器注册传递给 Android Attribution Reporting API(如果可用)有助于跨应用和跨网站实现最准确的归因。

以下示例展示了浏览器应用如何协同 Attribution Reporting API 提供准确的衡量结果(无论用户在浏览器应用中点击广告还是在非浏览器应用中点击广告):

3 天内的用户点击和转化示例
图 1. 跨浏览器和跨应用的来源和触发器注册示例
  • 第 1 天,用户在浏览器应用中点击了某广告。
    • 浏览器应用可以选择使用自己的效果衡量解决方案,或将 Web 广告点击的注册传递给 Attribution Reporting API。
  • 第 2 天,用户在非浏览器应用中点击了某广告。
    • 通过 API 将该点击注册为归因来源。浏览器应用无法看到此点击,因为事件发生在其他应用中。
  • 第 3 天,用户在浏览器应用中完成转化。
    • 如果浏览器应用使用自己的衡量解决方案注册点击和转化,并将该信息传递给 Attribution Reporting API,则广告技术平台不太可能跨衡量解决方案删除重复的转化报告。此外,广告技术平台可能会同时占用浏览器应用速率限制和 Attribution Reporting API 速率限制。因此,我们的建议是,如果 API 可用,应用应传递所有广告事件和转化以在该 API 上注册。

通过 WebView 注册归因来源和触发器

如果应用使用 WebView 展示 Web 内容而非原生 Android 广告,则可以申请加入许可名单(针对 registerWebSource()),并提供网站的顶级源以便与归因来源(而不是应用软件包名称)相关联。

与浏览器类似,WebView 支持将 registerWebTrigger() 用于触发器注册,这会将触发器与顶级源相关联。不支持 WebView 注册应用触发器;如果您有相关用例,请与我们联系。如需查看 WebView 支持的组合的完整列表,请参阅通过 WebView 进行的归因来源和触发器注册

与浏览器不同,WebView 仅在 Android 的 Attribution Reporting API 可用时才支持在 Attribution-Reporting-Eligible 标头中注册 OS。如果 Android 的 Attribution Reporting API 不可用,WebView 不会设置 Attribution-Reporting-Eligible 标头,也不会进行任何注册。

如需使用 OS 注册归因来源或触发器,请执行以下操作:

  • 广告技术平台应使用 Attribution-Reporting-Register-OS-Source 标头响应来源注册,这会从 WebView 发起对 registerSource()registerWebSource() 的二次 API 调用。
  • 广告技术平台还可以使用 Attribution-Reporting-Register-OS-Trigger 标头来响应触发器注册,这会从 WebView 发起对 registerWebTrigger()registerTrigger() 的二次 API 调用。

如需详细了解 WebView 是否会使用 registerSource()/registerWebSource()registerTrigger()/registerWebTrigger(),以及如何更改此行为,请参阅通过 WebView 进行的归因来源和触发器注册

过渡调试报告

Attribution Reporting API 支持一项称为过渡调试报告的可选功能,借助该功能,广告技术平台可以在广告 ID 可用时详细了解归因报告。调试报告分为两种:归因成功报告和详细报告。跨应用和跨网站归因支持这些报告,并且这两种报告包含相同的信息;唯一的区别在于发送调试报告时权限受控。

对于在同一应用内发生的网站到网站归因(例如,在同一浏览器应用内),归因成功报告和详细报告仅在第三方 Cookie 可用时提供,而不是基于广告 ID 的可用性。

对于应用到网站、网站到应用和网站到网站的跨应用归因,如果广告 ID 适用于应用端且广告技术平台可在网站端传递相同(正确)的广告 ID,系统会同时提供归因成功报告和详细报告。请参见下面的应用到网站示例,其中来源发生在发布商应用中,但触发器发生在浏览器应用中的广告主网站上。

如需为应用到网站启用归因成功调试报告,必须同时满足以下三个条件:

  • 用户不能选择停用会使用广告 ID 的个性化功能
  • 发布商应用必须已声明广告 ID 权限
  • 广告技术平台必须在触发器注册(从网站上下文)中传递广告 ID 值

若要为应用到网站启用详细调试报告:

  • 来源详细报告仅取决于发布商方的权限。若要发送来源详细报告,用户不得选择停用会使用广告 ID 的个性化功能,发布商应用必须已声明广告 ID 权限。
  • 触发器详细报告仅取决于触发器端(在此示例中为网站)权限。若要发送触发器详细报告,必须确保浏览器中有可用的第三方 Cookie。
  • 对于可以选择添加 source_debug_key 的触发器详细报告,如果广告 ID 对发布商应用可用,报告中会包含 source_debug_key

请注意,在所有情况下,广告技术平台仍然需要通过来源和触发器注册标头中的 debug_reporting 字典字段来接收详细调试报告。

针对应用的变更

我们将支持跨应用和跨网站途径进行归因,具体方法是允许应用使用一组新的网站上下文 API 调用,将网站归因来源和网站触发器的注册传递给 Android 上的 Attribution Reporting API。

完成下面几部分中的注册步骤后,应用/网站归因来源和触发器会存储在设备上,且 Attribution Reporting API 可以跨应用和网站途径执行来源优先的最后接触归因。

如需查看有关浏览器如何与 Android Attribution Reporting API 集成以实现跨应用和跨网站衡量的示例,请参阅 Privacy Sandbox for the Web 的方案。在该方案中,浏览器将添加以下请求标头:

  • Attribution-Reporting-Eligible 用于广播是否提供对归因的操作系统级支持。在本用例中,该标头指示 Android Attribution Reporting API 是否可用。
  • 如果可用,广告技术平台可以选择性地使用 Attribution-Reporting-Register-OS-Source 进行响应,从浏览器应用发起对 registerWebSource() 的二次 API 调用。
  • 广告技术平台还可以使用 Attribution-Reporting-Register-OS-Trigger 标头对触发器注册进行响应,从浏览器应用发起对 registerWebTrigger() 的二次 API 调用。

归因来源注册

注册归因来源时,应用可以调用 registerWebSource(),这需要以下参数:

  • 归因来源 URI:平台会向此列表中的每个 URI 发出请求,以提取与归因来源相关联的元数据。

    每个 URI 都应随附一个布尔值 Debug 标志,用于指明是否应将广告技术平台提供的调试键纳入报告中。
  • 输入事件InputEvent 对象(如果是点击事件)或 null(如果是观看事件)
  • 来源位置:来源的发生位置(发布商网站)。
  • 操作系统目标位置:发生触发器事件的应用软件包名称。
  • 网站目标位置:发生触发器事件的 eTLD+1。
  • 已验证目标位置:用于在用户点击时进行导航的 OS 或网站目标位置 URI intent。

当该 API 向归因来源 URI 发出请求时,广告技术平台应使用 HTTP 标头 Attribution-Reporting-Register-Source 返回归因来源元数据进行响应。此标头使用与应用到应用归因来源注册相同的字段,但有一些更改:

  • 该 API 会根据应用指定的目标位置来验证广告技术平台指定的目标位置。如果这两个目标位置不同,则 API 会舍弃归因来源注册。

    应用应在调用网站上下文 API 之前验证网站目标位置。对于点击,应用应检查指定的目标位置是否与用户导航到的目标位置相一致。
  • 该 API 会忽略 Attribution-Reporting-Redirects 中提供的任何重定向 URI。应用应自行跟踪重定向,并为每个重定向调用 registerWebSource(),以便可以根据需要应用自己的权限政策。

应用必须加入许可名单才能调用 registerWebSource()。如需加入许可名单,请填写此表单。该许可名单旨在缓解有关建立网站上下文信任的隐私疑虑。

触发器(转化)注册

对于触发器注册,应用可以调用 registerWebTrigger(),这需要以下参数:

  • 触发器 URI:平台会向此列表中的每个 URI 发出请求,以提取与触发器相关联的元数据
  • 目标位置:触发器的发生位置(广告客户网站)

通过 WebView 进行的归因来源和触发器注册

默认情况下,WebView 将使用 registerSource()registerWebTrigger()。这会在触发器事件发生时将来源与应用相关联,并将触发器与 WebView 的顶级来源相关联。

如果应用需要其他行为(例如在 WebView 中托管 Web 内容的行为),则需对 androidx.webkit.WebViewSettingsCompat 类使用 setAttributionRegistrationBehavior 方法。此方法将指定 WebView 是否应该调用 registerWebSource()/registerSource()registerWebTrigger()/registerTrigger()

setAttributionRegistrationBehavior 的可用选项如下:

说明 示例用例
APP_SOURCE_AND_WEB_TRIGGER(默认) 允许应用通过 WebView 注册应用来源(与应用软件包名称相关联的来源)和网站触发器(与 eTLD+1 相关联的触发器)。 使用 WebView(而非通过启用网络浏览)投放广告的应用
WEB_SOURCE_AND_WEB_TRIGGER 允许应用通过 WebView 注册网站来源和网站触发器。
注意:使用此选项的应用必须申请加入许可名单才能使用 registerWebSource()
基于 WebView 的浏览器应用,其中广告展示和转化可能都发生在 WebView 中的网站上。
APP_SOURCE_AND_APP_TRIGGER 允许应用通过 WebView 注册应用来源和应用触发器。 基于 WebView 的应用,其中广告展示和转化应始终与应用(而非 WebView 的 eTLD+1)相关联。
DISABLED 在 WebView 中停用来源注册和触发器注册。
请注意,对归因来源 URI 或触发器 URI 的初始网络调用可能仍会发生,但系统会舍弃所有响应,且不会在设备上存储任何内容。

隐私权和安全注意事项

对应用于报告的隐私保护机制的影响

如主要设计方案所述,API 对报告应用了隐私保护速率限制。一些限制将划分到源应用和目标应用中。注册网站归因来源或触发器时,速率限制将按源网站或目标网站(而非应用)划分。

如果应用使用单独的速率限制,则除了 API 的速率限制以外,攻击者还可以占用应用专有的速率限制。为缓解此问题,应用应确保未同时在应用的效果衡量解决方案和 Android Attribution Reporting API 中注册特定的归因来源。

建立网站上下文信任

在网站上下文 API 调用中,API 会信任应用以检测和指定源位置和目标位置。这可能会涉及隐私权和安全性方面的潜在注意事项:

  • 攻击者可以声称托管其自有网站,以尝试绕过任何针对来源可以传输的信息量的速率限制
  • 多个攻击者可以相互协作来分别注册各自的归因来源,并同时声明同一个来源网站。这可能会导致来源网站达到广告技术平台速率限制,并阻止实际来源网站注册合法的归因来源。

为了缓解此疑虑,我们将限制哪些浏览器或应用可以调用针对浏览器或应用的 registerWebSource() 以证明注册中使用的来源网站即为向用户显示的实际网站。填写此表单即可加入许可名单,以便调用 registerWebSource()

任何应用都可以调用 registerWebTrigger(),因为如果没有来源端冲突,则触发器端的隐私权和安全注意事项将不适用。

用户控制功能

只要可以在注册时定义用户控制功能或权限政策,应用就可以继续支持这些用户控制功能或权限政策。例如,如果应用允许任何网站级或用户级权限,则应评估这些权限并确定是否调用网站上下文 API。

此外,我们将支持来自应用的新 API 调用,以删除设备上为该应用存储的所有归因来源、触发器和待处理报告。例如,如果应用允许用户清除浏览记录,则用户可能希望调用 API 来删除用户设备上为该应用存储的归因来源、触发器和待处理报告。

未来的注意事项和待解决的问题

Attribution Reporting API 的应用到网站互操作性正在开发中。我们希望就以下几个想法向社区征求反馈:

  1. 在支持 Android Privacy Sandbox 的设备上,您将如何结合使用浏览器衡量解决方案与 Attribution Reporting API?您更倾向于将所有信息都传递给 Android 吗?
  2. 对于每个归因来源和触发器,都可能会收到 2 个 ping(一个来自浏览器/应用,另一个来自 Attribution Reporting),是否存在任何顾虑?
  3. 我们可以如何帮助您更轻松地跨不同 API 进行调试?
  4. 此方案未包含与应用和网站目标位置相关联的验证。未来,我们或许可以使用 Digital Asset Links 来检查关联以验证这些目标位置。这会阻止您的任何用例吗?使用 Digital Asset Links 执行此验证是否合理?
  5. 注册归因来源时,必须指定一个目标位置。在“网站到应用”用例中,您可能需要指定应用链接。您会使用什么格式来指定此应用链接?
  6. 在注册应用到网站归因来源时,需要使用 Android Attribution Reporting API 从应用注册该来源事件。例如,如果用户在应用中点击某条广告,然后在浏览器或浏览器的自定义标签页中打开点击的广告,那么应在应用中(而不是在浏览器上下文中)注册点击(来源事件)。如果您对此有疑虑,或者有其他用例不属于描述受支持流程的此问题所涵盖的类别,请与我们联系。