Privacy Sandbox on Android 开发者预览版现已推出!了解如何开始使用,并继续提供反馈

归因报告

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

提供反馈

现在,移动归因和衡量解决方案经常会使用跨方标识符,例如广告 ID。Attribution Reporting API 旨在通过消除对跨方用户标识符的依赖来提供更好的用户隐私保护,并支持跨应用和跨网站进行归因和转化衡量的关键用例。

该 API 具有以下结构机制,这些机制提供了一个用于加强隐私保护的框架,本文档后面几个部分将对其进行更加详细的介绍:

上述机制可限制跨两个不同应用或网域关联用户身份的能力。

Attribution Reporting API 支持以下用例:

  • 转化报告:通过向广告主显示各个维度(例如广告系列、广告组和广告素材)的转化(触发器)次数和转化(触发器)值,协助广告主衡量其广告系列的效果。
  • 优化:通过提供可用于训练机器学习模型的每次展示归因数据,提供有助于优化广告支出的事件级报告。
  • 无效活动检测:提供可用于无效流量和广告欺诈检测与分析的报告。

概括来讲,Attribution Reporting API 的运作方式如下(本文档后面几个部分将对其进行更加详细的介绍):

  1. Adtech 完成注册流程,以使用 Attribution Reporting API。
  2. 广告技术平台向 Attribution Reporting API 注册归因来源(广告点击或观看)。
  3. 广告技术平台向 Attribution Reporting API 注册触发器(广告主应用或网站上的用户转化)。
  4. Attribution Reporting API 将触发器与归因来源进行匹配(一种转化归因),并且一个或多个触发器通过事件级报告和可汇总的报告发送到设备外的广告技术平台。

获取对 Attribution Reporting API 的访问权限

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

注册归因来源(点击或观看)

Attribution Reporting API 会将广告点击和观看作为归因来源。如需注册广告点击或广告观看,请调用 registerSource()。该 API 需要以下参数:

  • 归因来源 URI:平台将向此 URI 发出请求,以便获取与归因来源关联的元数据。
  • 输入事件InputEvent 对象(如果是点击事件)或 null(如果是观看事件)。

当该 API 向归因来源 URI 发出请求时,广告技术平台应使用新的 HTTP 标头 Attribution-Reporting-Register-Source 返回归因来源元数据进行响应,其中包含以下字段:

  • Source event ID:一个可对 64 位无符号整数进行编码的 DOMString。 该值表示与相应归因来源(广告点击或观看)关联的事件级数据。
  • Destination:一个来源,其 eTLD+1 或应用软件包名称表示触发器事件的发生位置。
  • Expiry(选填):过期时间(以秒为单位),超过该时间后应从设备中删除相应来源。默认值为 30 天,最小值为 2 天,最大值为 30 天。该值会四舍五入到最接近的天数。
  • Source priority(选填):一个有符号的 64 位整数,在有多个归因来源可与指定的触发器相关联时,用于选择该触发器应与哪个归因来源相关联。

    收到触发器后,该 API 会查找来源优先级值最高的匹配归因来源,并生成报告。每个 Adtech 平台都可以定义自己的优先级策略。如需详细了解优先级对归因有何影响,请参阅优先级示例部分。

    值越高,表示优先级越高。

  • Install and post-install attribution windows(选填):用于确定安装后事件的归因,本文档后面部分将对其进行介绍。

  • Filter data(选填):用于选择性地过滤某些触发器,从而有效地忽略它们。如需了解详情,请参阅本页的触发器过滤器部分。

  • Aggregation keys(选填):指定要为可汇总报告使用的细分

(可选)归因来源元数据响应可能会在归因报告重定向标头中包含其他数据。这些数据包含重定向网址,可供多个广告技术平台注册请求

开发者指南包含一些示例,展示了如何接受来源注册

以下步骤显示了一个示例工作流程:

  1. 广告技术平台 SDK 调用该 API 以启动归因来源注册,并指定该 API 要调用的 URI:

    registerSource(
        Uri.parse("https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA"),
        myClickEvent);
    
  2. 该 API 使用以下标头之一向 https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA 发出请求:

    <!-- For click events -->
    Attribution-Reporting-Source-Info: navigation
    
    <!-- For view events -->
    Attribution-Reporting-Source-Info: event
    
  3. 该广告技术平台的 HTTPS 服务器使用包含以下内容的标头进行回复:

    Attribution-Reporting-Register-Source: {
        "destination": "android-app://com.advertiser.example",
        "source_event_id": "234",
        "expiry": "60000",
        "priority": "5"
    }
    Attribution-Reporting-Redirects: https://adtechpartner1.example?their_ad_click_id=567,
    https://adtechpartner2.example?their_ad_click_id=890
    
  4. 该 API 向 Attribution-Reporting-Redirects 中指定的每个网址发出请求。在本示例中,指定了两个广告技术合作伙伴网址,因此 API 将向 https://adtechpartner1.example?their_ad_click_id=567 发出一个请求,并向 https://adtechpartner2.example?their_ad_click_id=890 发出另一个请求。

  5. 该广告技术平台的 HTTPS 服务器使用包含以下内容的标头进行回复:

    Attribution-Reporting-Register-Source: {
        "destination": "android-app://com.advertiser.example",
        "source_event_id": "789",
        "expiry": "120000",
        "priority": "2"
    }
    

根据前面步骤中显示的请求,注册了三个导航(点击)归因来源。

注册触发器(转化)

广告技术平台可以使用 registerTrigger() 方法注册触发器,即转化(例如安装或安装后事件)。

registerTrigger() 方法需要触发器 URI 参数。该 API 会向此 URI 发出请求,以便获取与触发器关联的元数据。

该 API 会跟踪重定向。广告技术平台服务器响应应包含一个称为 Attribution-Reporting-Register-Event-Trigger 的 HTTP 标头,该标头表示关于一个或多个已注册触发器的信息。标头的内容应经过 JSON 编码,并且包含以下字段:

  • Trigger data:该数据用于识别触发器事件(如果是 3 位,则表示点击;如果是 1 位,则表示观看)
  • Trigger priority(选填):有符号的 64 位整数,表示相应触发器相对于同一归因来源的其他触发器的优先级。如需详细了解优先级对报告有何影响,请参阅优先级示例部分。
  • Deduplication key(选填):有符号的 64 位整数,用于识别以下情况:同一广告技术平台针对同一归因来源多次注册了同一触发器
  • Aggregation keys(选填):一个字典列表,用于指定汇总键以及哪些可汇总的报告应汇总它们的值。
  • Aggregation values(选填):对每个键有贡献的值的列表。
  • Attribution Reporting Filter(选填):用于选择性地过滤触发器或触发器数据。如需了解详情,请参阅本页的触发器过滤器部分。

(可选)广告技术平台服务器响应可能会在归因报告重定向标头中包含其他数据。这些数据包含重定向网址,可供多个广告技术平台注册请求

多个广告技术平台可以使用 Attribution-Reporting-Redirects 字段中的重定向或多次调用 registerTrigger() 方法来注册同一触发器事件。我们建议您使用 Deduplication key 字段,以避免在同一个广告技术平台为同一个触发器事件提供了多个响应时,报告中包含重复的触发器。详细了解如何以及何时使用重复信息删除键

开发者指南包含一些示例,展示了如何接受触发器注册

以下步骤显示了一个示例工作流程:

  1. 广告技术平台 SDK 会调用该 API,以使用预先注册的 URI 来启动触发器注册:如需了解详情,请参阅注册 Privacy Sandbox 帐号

    registerTrigger(
        Uri.parse("https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA"));
    
  2. 该 API 会向 https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA 发出请求。

  3. 该广告技术平台的 HTTPS 服务器使用包含以下内容的标头进行回复:

    Attribution-Reporting-Register-Event-Trigger: {
        "trigger_data": "1122",
        // This returns 010 for click-through conversions (CTCs) and 0 for
        // view-through conversions (VTCs) in reports
        "priority": "3",
        "deduplication_key": "3344",
    }
    Attribution-Reporting-Redirects: https://adtechpartner.example?app_install=567
    
  4. 该 API 向 Attribution-Reporting-Redirects 中指定的每个网址发出请求。在此示例中,因为仅指定了一个网址,所以该 API 会向 https://adtechpartner.example?app_install=567 发出请求。

  5. 该广告技术平台的 HTTPS 服务器使用包含以下内容的标头进行回复:

    Attribution-Reporting-Register-Event-Trigger: {
        "trigger_data": "5566",
        "priority": "3",
        "deduplication_key": "3344"
    }
    

    根据前面步骤中的请求注册了两个触发器。

归因功能

以下几部分将介绍 Attribution Reporting API 如何将转化触发器与归因来源进行匹配。

采用了来源优先归因算法

Attribution Reporting API 采用了来源优先归因算法,以便将触发器(转化)与归因来源进行匹配。

您可以通过优先级参数自定义触发器的归因来源:

  • 您可以将触发器归因于特定广告事件,优先于其他事件。例如,您可以选择更注重点击而非观看,或者重点关注来自某些广告系列的事件。
  • 您可以配置归因来源和触发器,以便在达到速率限制时更有可能收到对您更重要的报告。例如,您可能希望确保可出价转化或高价值转化有更大的机会出现在这些报告中。

如果多个广告技术平台注册了一个归因来源(如本文档后面部分所述),那么系统会针对每个广告技术平台独立进行这项归因。对于每个广告技术平台,触发器事件都会归因于优先级最高的归因来源。如果存在多个具有相同优先级的归因来源,该 API 会选择最后注册的归因来源。未被选中的所有其他归因来源都会被舍弃,并且不再符合参与后续触发器归因的条件。

触发器过滤器

来源注册和触发器注册包含额外的可选功能,用于执行以下操作:

  • 选择性地过滤某些触发器,从而有效地忽略它们。
  • 根据来源数据为事件级报告选择触发器数据。
  • 选择从事件级报告中排除某个触发器。

如需选择性地过滤触发器,广告技术平台可以在来源注册和触发器注册期间指定过滤器数据(由键和值组成)。如果为来源和触发器指定了相同的键,那么当交集为空时,系统会忽略触发器。例如,来源可以指定 "product": ["1234"],其中 product 是过滤器键,1234 是值。如果触发器过滤器设置为 "product": ["1111"],就会忽略该触发器。如果没有与 product 匹配的触发器过滤器键,就会忽略这些过滤器。

Adtech 平台也可以根据来源事件数据选择触发器数据。例如,API 会将 source_type 自动生成为 navigationevent。在触发器注册期间设置 trigger_data 时,可针对 "source_type": ["navigation"] 设置为一个值而针对 "source_type": ["event"] 设置为另一个不同值。

如果满足以下任一条件,便会从事件级报告中排除触发器:

  • 未指定 trigger_data
  • 来源和触发器指定了相同的过滤器键,但值不一致。请注意,在这种情况下,事件级报告和可汇总报告都会忽略触发器。

安装后归因

在有些情况下,即使最近发生了其他符合条件的归因来源,也需要将安装后触发器归因于促成安装的同一归因来源。

该 API 允许广告技术平台设置安装后归因期,因此可以支持此用例:

  • 注册归因来源时,请指定安装归因回溯期,即预计发生安装事件的时间范围(通常为 2-7 天,可接受的范围为 2-30 天)。将此时间范围指定为秒数。
  • 注册归因来源时,请指定安装后归因专享回溯期,在此期间内的任何安装后触发器事件都应与促成安装的归因来源相关联(通常为 7-30 天,可接受的范围为 0-30 天)。将此时间范围指定为秒数。
  • Attribution Reporting API 会验证应用安装发生时间,并在内部按照来源优先归因逻辑将安装归因于相应的归因来源。不过,系统不会将安装事件发送到广告技术平台,也不会计入平台各自的速率限制。
  • 应用安装验证适用于任何下载的应用。
  • 安装后归因回溯期内发生的所有后续触发器都归因于与已验证安装相同的归因来源,前提是该归因来源符合条件。

    我们正在想方设法支持用户卸载并重新安装应用的用例。

将来,我们可能会探索通过扩展设计来支持更先进的归因模型。

下表显示了一个示例,展示 Adtech 可以如何使用安装后归因。该示例假设所有归因来源和触发器都由同一广告技术网络注册,且所有优先级均相同。

事件 事件发生日 备注
点击 1 1 install_attribution_window 设置为 172800(2 天),post_install_exclusivity_window 设置为 864000(10 天)
已验证安装 2 API 在内部对已验证安装进行归因,但这些安装不会被视为触发器。因此,此时不会发送任何报告。
触发器 1(首次打开) 2 由 Adtech 注册的第一个触发器。在此示例中,它表示首次打开,但可以是任何触发器类型。
归因于点击 1(与已验证安装的归因一致)。
点击 2 4 install_attribution_windowpost_install_exclusivity_window 使用与点击 1 相同的值
触发器 2(安装后) 5 由 Adtech 注册的第二个触发器。在此示例中,它表示安装后的转化,例如购买。
归因于点击 1(与已验证安装的归因一致)。
点击 2 被舍弃,不符合参与后续归因的条件。

下面列出了关于安装后归因的一些其他说明:

  • 如果已验证安装并非发生在 install_attribution_window 指定的天数内,就不会应用安装后归因。
  • 已验证安装并非由广告技术平台注册,不会在报告中被发送出去,也不会计入广告技术平台的速率限制。已验证安装仅用于标识归因于安装的归因来源。
  • 在上表的示例中,触发器 1 和触发器 2 分别表示首次打开和安装后转化。不过,广告技术平台可以注册任何类型的触发器。换言之,第一个触发器并不一定要是首次打开。
  • 如果在 post_install_exclusivity_window 到期后注册更多触发器,点击 1 仍符合参与归因的条件(假设该事件尚未过期且尚未达到其速率限制)。
    • 如果注册了优先级更高的归因来源,点击 1 可能仍会丢失或被舍弃。
  • 如果卸载后重新安装广告主应用,会将重新安装计为新的已验证安装。
  • 如果点击 1 是观看事件,“首次打开”和安装后触发器仍会归因于该事件。该 API 限定每次观看只能归因于一个触发器,但安装后归因除外,在此情况下,允许将每次观看归因于最多两个触发器。在安装后归因的情况下,广告技术平台可能会收到 2 个不同的报告期。

支持基于应用的触发器路径和基于网站的触发器路径的所有组合

借助 Attribution Reporting API,可以对单个 Android 设备上的以下触发器路径进行归因:

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

我们允许网络浏览器支持已在网络上公开的新功能,例如与 Privacy Sandbox for the Web's Attribution Reporting API(可以调用 Android API 来实现跨应用和跨网站进行归因)相似的功能。

了解广告技术平台和应用需要做出哪些更改才能支持跨应用和跨网站衡量的触发路径。

为单个归因来源确定多个触发器的优先级

一个归因来源可能会导致多个触发器。例如,购买流程可能会涉及“应用安装”触发器、一个或多个“添加到购物车”触发器和“购买”触发器。每个触发器都会根据来源优先归因算法(本文档后面部分将对其进行介绍)归因于一个或多个归因来源。

可归因于单个归因来源的触发器数量有限制;如需了解详情,请参阅本文档后面的在归因报告中查看衡量数据部分。如果有多个触发器超出了这些限制,引入优先级逻辑有助于恢复最有价值的触发器。例如,广告技术平台的开发者可能希望优先获取“购买”触发器,而非“添加到购物车”触发器。

为了支持这种逻辑,可以为触发器设置单独的优先级字段,并且在指定的报告期内,在应用限制之前先选择优先级最高的触发器。

允许多个广告技术平台注册归因来源或触发器

有多个广告技术平台接收归因报告的情况很常见,这通常是为了执行跨广告网络重复信息删除。因此,该 API 允许多个 Adtech 注册同一个归因来源或触发器。广告技术平台必须同时注册归因来源和触发器才能接收来自该 API 的回传,并在广告技术平台向该 API 注册的归因来源和触发器间完成归因。

希望使用第三方执行跨广告网络重复信息删除的广告主可以使用如下所述的方式继续这样做:

  • 设置内部服务器,以注册并从该 API 接收报告。
  • 继续使用现有的移动设备衡量合作伙伴。

归因来源

registerSource() 方法支持归因来源重定向:

  1. 调用 registerSource() 方法的广告技术平台可以在响应中提供一个额外的 Attribution-Reporting-Redirects 字段,该字段表示合作伙伴广告技术的重定向网址集合。
  2. 然后,该 API 会调用重定向网址,以便合作伙伴广告技术平台可以注册归因来源。

Attribution-Reporting-Redirects 字段中可以列出多个合作伙伴广告技术平台网址,但合作伙伴广告技术平台无法指定自己的 Attribution-Reporting-Redirects 字段。

该 API 还允许不同的广告技术平台各自调用 registerSource()

触发器

对于触发器注册,系统会以类似方式支持第三方:广告技术平台可以使用额外的 Attribution-Reporting-Redirects 字段,也可以各自调用 registerTrigger() 方法。

当广告主使用多个广告技术平台来注册同一个触发器事件时,应使用重复信息删除键。重复信息删除键的作用是,针对相同广告技术平台注册的相同事件区分重复的报告。例如,某广告技术平台可能以 SDK 直接调用 API 注册了一个触发器,同时又将其网址包含在另一个广告技术平台调用的重定向字段中。如果未提供重复信息删除键,重复的触发器可能会作为不同的触发器回报给每个广告技术平台。

处理重复的触发器

Adtech 可能会向该 API 多次注册同一触发器。场景包括:

  • 用户多次执行同一操作(触发器)。例如,用户在同一报告期内多次浏览同一产品。
  • 广告主应用使用多个 SDK 进行转化衡量,所有这些 SDK 都会重定向到同一个广告技术平台。例如,广告主应用使用 2 个衡量合作伙伴,即 MMP 1 和 MMP 2。这两个 MMP 都会重定向到广告技术平台 3。当触发器发生时,两个 MMP 都会向 Attribution Reporting API 注册该触发器。然后,广告技术平台 3 收到针对同一触发器的两个单独的重定向:一个来自 MMP 1,另一个来自 MMP 2。

在这些情况下,您可以采用多种方式来抑制关于重复触发器的事件级报告,以降低超出应用于事件级报告的速率限制的可能性。建议使用重复信息删除键。

推荐方法:重复信息删除键

建议广告主应用将唯一的重复信息删除键传递给它用于转化衡量的所有广告技术平台 或 SDK。当发生转化时,该应用会将重复信息删除键传递给 Adtech 或 SDK。然后,这些广告技术平台或 SDK 会继续使用 Attribution-Reporting-Redirects 中所指定网址内的参数将重复信息删除键传递给重定向。

广告技术平台可以选择仅注册具有给定重复信息删除键的第一个触发器,也可以选择注册多个触发器或注册所有触发器。在注册重复的触发器时,广告技术平台可以指定 deduplication_key

如果广告技术平台使用同一重复信息删除键和归因的来源注册多个触发器,事件级报告中仅会发送第一个已注册的触发器。重复的触发器仍会在加密的可汇总报告中发送。

替代方法:广告技术平台同意为每个广告主采用不同的触发器类型

如果广告技术平台不希望使用重复信息删除键,或广告主应用无法传递重复信息删除键,则可以使用替代选项。衡量指定广告主转化情况的所有广告技术平台必须相互配合,才能为每个广告主定义不同的触发器类型。

启动触发器注册调用的广告技术平台(例如 SDK)会在 Attribution-Reporting-Redirects 中所指定的网址内包含参数(例如 duplicate_trigger_id)。该 duplicate_trigger_id 参数可以包含相应广告主的 SDK 名称和触发器类型等信息。这样一来,广告技术平台便可将这些重复的触发器的一部分发送到事件级报告。广告技术平台还可以在其汇总键中包含此 duplicate_trigger_id

跨广告网络归因示例

在本部分所述的示例中,广告主使用了两个广告投放技术平台(广告技术平台 A 和广告技术平台 B)和一个衡量合作伙伴 (MMP)。

首先,广告技术平台 A、广告技术平台 B 和 MMP 必须各自完成注册,才能使用 Attribution Reporting API。如需了解详情,请参阅注册 Privacy Sandbox 帐号

下面的列表提供了一系列假设的用户操作(每天发生一个),以及 Attribution Reporting API 如何针对广告技术平台 A、广告技术平台 B 和 MMP 处理这些操作:

第 1 天:用户点击 Adtech A 投放的广告

广告技术平台 A 使用其 URI 调用 registerSource()。API 向该 URI 发出请求,并使用广告技术平台 A 的服务器响应中的元数据注册该点击。

广告技术平台 A 还会在 Attribution-Reporting-Redirects 标头中添加 MMP 的 URI。API 向 MMP 的 URI 发出请求,并使用 MMP 服务器响应中的元数据注册该点击。

第 2 天:用户点击 Adtech B 投放的广告

广告技术平台 B 使用其 URI 调用 registerSource()。API 向该 URI 发出请求,并使用广告技术平台 B 的服务器响应中的元数据注册该点击。

与广告技术平台 A 一样,广告技术平台 B 同样在 Attribution-Reporting-Redirects 标头中添加了 MMP 的 URI。API 向 MMP 的 URI 发出请求,并使用 MMP 服务器响应中的元数据注册该点击。

第 3 天:用户观看由 Adtech A 投放的广告

API 的响应方式与第 1 天相同,只不过会为 Adtech A 和 MMP 各注册一次观看。

第 4 天:用户安装应用,该应用使用 MMP 来衡量转化

MMP 使用其 URI 调用 registerTrigger()。API 向该网址发出请求,并使用 MMP 服务器响应中的元数据注册该转化。

MMP 还会在 Attribution-Reporting-Redirects 标头中添加广告技术平台 A 和广告技术平台 B 的 URI。API 向 Adtech A 和 Adtech B 的服务器发出请求,并使用服务器响应中的元数据相应地注册该转化。

图 1 说明了上述列表中描述的过程:

图 1. 关于 Attribution Reporting API 如何响应一系列用户操作的示例。

归因过程的工作原理如下:

  • 广告技术平台 A 将点击的优先级设为高于观看的优先级,因此将安装归因于第 1 天的点击。
  • 广告技术平台 B 将安装归因于第 2 天。
  • MMP 将点击的优先级设为高于观看的优先级,并将安装归因于第 2 天的点击。第 2 天的点击是优先级最高且最近发生的广告事件。

无重定向的跨广告网络归因

虽然我们建议使用重定向以允许多个广告技术平台注册归因来源和触发器,但我们知道,在某些情况下使用重定向不可行。本部分将详细介绍如何在不进行重定向的情况下支持跨广告网络归因。

概要流程

  1. 在来源注册时,广告投放技术联盟会共享其来源汇总键。
  2. 触发注册时,广告主或衡量合作伙伴会选择要使用的来源端键部分,并指定其归因配置。
  3. 归因取决于归因配置、共享键,以及由该广告主或衡量合作伙伴实际注册的任何来源(例如,其他已启用重定向的广告投放技术联盟)。
  4. 如果触发器归因为来自非重定向广告投放技术的来源,则广告主或衡量合作伙伴可以接收可汇总的报告,其中会汇总第 2 步中定义的来源和触发器键部分。

来源注册

在来源注册时,广告投放技术联盟可以选择共享其来源汇总键或一部分来源汇总键,而不是重定向。广告投放技术平台并不需要在其可汇总报告中实际使用这些来源键,而且可以仅在需要时代表广告主或衡量合作伙伴声明它们。

共享汇总键可供为同一广告主注册触发器的任何广告技术平台使用。不过,广告投放技术平台和触发器衡量广告技术平台将共同协作来决定需要哪些类型的汇总键、其名称,以及如何将这些键解码为可读维度。

触发器注册

在触发器注册时,衡量广告技术平台会选择要将哪些来源端键部分应用于每个触发器键部分,包括广告投放技术平台共享的任何内容。

此外,衡量广告技术平台还必须通过新的归因配置 API 调用来指定广告瀑布流归因逻辑。采用这种配置时,广告技术平台可以指定来源优先级、有效期并过滤掉其无法查看的来源(例如,未使用重定向的来源)。

归因

Attribution Reporting API 会根据衡量广告技术平台的归因配置、共享键以及所注册的任何来源,为该广告技术平台执行来源优先的最后接触归因。例如:

  • 用户点击了广告技术平台 A、B、C 和 D 投放的广告。然后,用户安装了广告主的应用,该应用使用衡量广告技术合作伙伴 (MMP)。

  • 广告技术平台 A 将其来源重定向到 MMP。

  • 广告技术平台 B 和 C 不会重定向,但会共享其汇总键。

  • 广告技术平台 D 既不会重定向也不会共享汇总键。

MMP 注册广告技术平台 A 的来源,并定义了包含广告技术平台 B 和广告技术平台 D 的归因配置。

现在,MMP 的归因包括:

  • 广告技术平台 A,因为 MMP 注册了该广告技术平台重定向的来源。

  • 广告技术平台 B,因为广告技术平台 B 共享了键,而且 MMP 已将其纳入归因配置。

MMP 的归因不包括:

  • 广告技术平台 C,因为 MMP 未将其纳入归因配置。

  • 广告技术平台 D,因为它们既不会重定向也不会共享汇总键。

在归因报告中查看衡量数据

Attribution Reporting API 支持以下类型的报告(本文档后面将对其进行更加详细的介绍):

  • 事件级报告可将特定归因来源(点击或观看)与位数有限的高保真度触发器数据相关联。
  • 可汇总的报告不一定与特定归因来源相关联。与事件级报告相比,这些报告可提供更丰富、保真度更高的触发器数据,但这些数据只能以汇总形式提供。

这两种报告互为补充,可以同时使用。

事件级报告

将触发器归因于归因来源后,系统会生成事件级报告,并将其存储在设备上,直到可以在某个报告发送期(后文将详细介绍)内将其发回到每个广告技术平台的回传网址。

如果只需极少量的触发器相关信息,事件级报告非常有用。对于点击,事件级触发器数据只能有 3 位,这意味着,可以为触发器指定 8 个类别中的一个。对于观看,事件级触发器数据只能有 1 位。此外,事件级报告不支持对高保真度触发器端数据(例如具体价格或触发时间)进行编码。由于归因是在设备上进行的,因此事件级报告中不支持跨设备分析。

事件级报告包含诸如以下数据:

  • 目标位置:表示触发器发生位置的广告主应用软件包名称或 eTLD+1
  • 归因来源 ID注册归因来源时使用的归因来源 ID
  • 触发器类型:1 或 3 位低保真度触发器数据,具体取决于归因来源的类型

为所有报告应用的隐私保护机制

广告技术平台数量限制

可通过 API 注册或接收报告的广告技术平台的数量有限制,当前方案如下:

  • 每 {来源应用、目标应用、30 天、设备} 100 个与归因来源相关联的广告技术平台。
  • 每 {来源应用、目标应用、30 天、设备} 10 个与归因触发器相关联的广告技术平台。
  • 10 个广告技术平台可以注册单个归因来源或触发器(通过 Attribution-Reporting-Redirects

这些限制是在考虑了归因来源和触发器的优先级之后应用的。

冷却期和速率限制

为了限制(来源、目标)对之间的用户身份泄露量,该 API 限制了用户在给定时间段内发送的总信息量。

当前方案对每个 Adtech 的限制为每 {来源应用、目标应用、30 天、设备} 100 个归因触发器。

唯一目标数量

该 API 对 Adtech 可尝试衡量的目标数量有限制。限值越低,广告技术平台就越难使用该 API 尝试衡量与展示的广告无关的用户浏览活动。

当前方案对每个广告技术平台的限制为每个来源应用 100 个具有未过期来源的不同目标。

为事件级报告应用的隐私保护机制

触发器数据的保真度有限

该 API 为浏览型转化触发器提供 1 位数据,为点击触发器提供 3 位数据。归因来源会继续支持完整的 64 位元数据。

您应评估是否以及如何减少触发器中表达的信息,以便能够通过事件级报告中有限的位数来表示。

差分隐私噪声框架

该 API 的目标是,通过使用 k-随机化响应为每个来源事件生成含噪声的输出,使事件级衡量满足本地差分隐私要求。

针对是否如实报告归因来源事件应用噪声。系统会在设备上注册一个归因来源,归因来源正常注册的概率为 $ 1-p $,并且设备从该 API 的所有可能输出状态(包括完全不报告任何内容,或提供多份虚假报告)中随机选择的概率为 $ p $。

如果满足以下等式,则 k-随机化响应就是一种 epsilon 差分隐私算法:

\[ p = \frac{k}{k + e^ε - 1} \]

如果 ε 的值较低,实际输出会受到 k-随机化响应机制的保护。我们还在对确切的噪声参数进行研究,并且可能会根据反馈进行更改,当前方案如下:

  • p=0.24%(对于导航来源)
  • p=0.00025%(对于事件来源)

可用触发器(转化)的限制

每个归因来源的触发器数量有限制,当前方案如下:

  • 1-2 个触发器(如果广告归因来源是观看)
  • 3 个触发器(如果广告归因来源是点击)

这些限制是在考虑了归因来源和触发器的优先级之后应用的。

发送报告的具体时间范围

对于广告观看这种归因来源,报告会在来源过期 1 小时后发送。您可以配置此过期天数,但它不能少于 2 天,也不能超过 30 天。

广告点击这种归因来源的报告无法配置,并且在来源过期之前的指定时间点(相对于来源注册时间的时间点)发送。从归因来源注册到过期之间的时间会拆分为多个报告期。每个报告期都有一个截止时间(从归因来源注册时间算起)。在每个报告期结束时,设备都会收集自上一个报告期以来发生的所有触发器,并发送定期报告。该 API 支持以下报告期:

  • 2 天:设备会收集归因来源注册后最多 2 天内发生的所有触发器。报告会在归因来源注册 2 天零 1 小时后发送。
  • 7 天:设备会收集归因来源注册后 2 到 7 天内发生的所有触发器。 报告会在归因来源注册 7 天零 1 小时后发送。
  • 自定义时长,由归因来源的“expiry”属性定义。报告会在指定过期时间过去 1 小时后发送。该值不能少于 2 天,也不能超过 30 天。

可汇总的报告

事件级报告相比,可汇总的报告可以更快地提供来自设备的触发器数据,并且保真度更高。这些保真度更高的数据只能以汇总方式获取,并且不会与特定触发器或用户相关联。汇总键最多可为 128 位,这使得可汇总的报告可以报告多种用例,例如:

  • 关于触发器值(如收入)的报告
  • 处理更多触发器类型

此外,可汇总报告使用与事件级报告相同的来源优先归因逻辑,但支持更多归因于点击或观看的转化。

关于 Attribution Reporting API 如何准备和发送可汇总报告的总体设计(如图 2 所示)如下:

  1. 设备向广告技术平台发送加密的可汇总报告。在生产环境中,广告技术平台无法直接使用这类报告。
  2. 广告技术平台向汇总服务发送一批可汇总的报告以进行汇总。
  3. 汇总服务读取一批可汇总的报告,然后对其进行解密和汇总。
  4. 最终的汇总数据会以摘要报告的形式发回到广告技术平台。 {: .external}
图 2. Attribution Reporting API 准备和发送可汇总报告时遵循的流程。

可汇总的报告包含以下与归因来源相关的数据:

  • 目标位置:表示触发器出现位置的应用软件包名称或 eTLD+1 网址。
  • 日期:以归因来源表示的事件的发生日期。
  • 载荷:触发器值,以加密的键值对形式收集,在可信的汇总服务中用于计算汇总数据。

汇总服务

以下服务提供了汇总功能,并且有助于防范对汇总数据的不当访问。

这些服务由不同的负责方(本文档后面将对其进行更加详细的介绍)进行管理:

  • 汇总服务是广告技术平台预计会部署的唯一服务。
  • 密钥管理隐私预算服务由称为“验证方”的可信方运行。这些验证方负责验证运行汇总服务的代码是否为 Google 提供的公开代码,并验证所有汇总服务用户是否享受相同的密钥和预算服务。
汇总服务

Adtech 平台必须提前部署基于 Google 提供的二进制文件的汇总服务。

该汇总服务在托管于云端的可信执行环境 (TEE) 中运行。TEE 具有以下安全优势:

  • 它可确保在 TEE 中运行的代码是由 Google 提供的特定二进制文件。除非满足此条件,否则汇总服务无法获取运行所需的解密密钥。
  • 它可为运行中的进程提供安全保障,使其免于被外部监控或篡改。

这些安全优势使得汇总服务可以更安全地执行敏感操作,例如访问加密数据。

如需详细了解汇总服务的设计、工作流程和安全注意事项,请参阅 GitHub 上的汇总服务文档

密钥管理服务

这项服务负责验证汇总服务运行的是否为经过批准的二进制文件版本,如果是,则为广告技术平台中的汇总服务提供其触发器数据的正确解密密钥。

隐私预算服务

这项服务负责跟踪广告技术平台的汇总服务访问特定触发器(可以包含多个汇总键)的频率,并限制为仅可以访问适当数量的解密数据。可以对每个触发器执行一次解密。

Aggregatable Reports API

用于为可汇总的报告创建贡献内容的 API 使用的基本 API 与为事件级报告注册归因来源时使用的基本 API 相同。以下部分介绍了该 API 的扩展。

注册可汇总的来源数据

当该 API 向归因来源 URI 发出请求时,广告技术平台可以使用新的 HTTP 标头 Attribution-Reporting-Register-Aggregate-Source 进行响应,借此注册一个名为 histogram_contributions 的汇总键列表。对于每个汇总键,该列表中都包含以下字段:

  • Source event ID:键名称字符串。用作联接键,与触发器端键组合在一起后形成最终键。
  • Key piece:键的位串值。

最终直方图分区键在触发时通过对这些部分和触发器端部分执行二元 OR 运算进行完全定义。

最终键不得超过 128 位;如果键超过 128 位,就会被截断。这意味着 JSON 中的十六进制字符串不得超过 32 位。

详细了解汇总键的结构以及如何配置汇总键。

在下面的示例中,广告技术平台使用该 API 收集以下信息:

  • 在广告系列级汇总转化次数
  • 在地理位置级汇总购买价值
// This is where the Attribution-Reporting-Register-Source object appears when
// an adtech registers an attribution source.

// Attribution source metadata specifying histogram contributions in aggregate report.
Attribution-Reporting-Register-Aggregatable-Source:
[{
// Generates a "0x159" key piece named (low order bits of the key) for the key
// named "campaignCounts".
  "id": "campaignCounts",
// User saw an ad from campaign 345 (out of 511).
  "key_piece": "0x159",
},
{
// Generates a "0x5" key piece (low order bits of the key) for the key named "geoValue"
  "id": "geoValue",
// Source-side geo region = 5 (US), out of a possible ~100 regions.
  "key_piece": "0x5",
}]

注册可汇总的触发器

触发器注册包括两个额外的标头。

第一个标头用于在触发器端注册一个汇总键列表。广告技术平台应使用 HTTP 标头 Attribution-Reporting-Register-Aggregatable-Trigger-Data 进行响应。对于每个汇总键,该列表中都包含以下字段:

  • Key piece:键的位串值。
  • Source keys:一个字符串列表,其中包括归因来源端键的名称,触发器键应与这些键组合在一起以形成最终键。

第二个标头用于注册应对每个键有贡献的值的列表。广告技术平台应使用 HTTP 标头 Attribution-Reporting-Register-Aggregatable-Values 进行响应。

第二个标头用于注册应对每个键有贡献的值的列表,可为 $ [1, 2^{16}] $ 范围内的整数。广告技术平台应使用 HTTP 标头 Attribution-Reporting-Register-Aggregatable-Values 进行响应。

每个触发器都可以对可汇总报告做出多项贡献。对任何指定来源事件的贡献总量受 $ L1 $ 参数制约,对于指定的来源,对所有汇总键的贡献(值)的总和不得超过该参数。$ L1 $ 是指每个来源事件的直方图贡献的 L1 灵敏度或范数。超过这些限制会导致未来的贡献悄然下降。初始方案是将 $ L1 $ 设为 $ 2^{16} $ (65536)。

汇总服务中的噪声会按照与此参数成一定比例进行缩放。因此,建议根据分配给指定汇总键的 $ L1 $ 预算部分,适当缩放为指定汇总键报告的值。该方法有助于确保,在应用了噪声时,汇总报告能够尽可能保持较高的保真度。这种机制非常灵活,可以支持多种汇总策略。

在以下示例中,通过在 campaignCountsgeoValue 之间分配 $ L1 $ 贡献,将在这两者之间平均分配隐私预算:

// This is where the Attribution-Reporting-Register-Event-Trigger object appears
// when an adtech registers a conversion trigger.

// Specify a list of dictionaries that generates aggregation keys.
Attribution-Reporting-Register-Aggregatable-Trigger-Data:
[
  // Each dictionary independently adds pieces to multiple source keys.
  {
  // Conversion type purchase = 2 at a 9-bit offset, i.e. 2 << 9.
  // A 9-bit offset is needed because there are 511 possible campaigns, which
  // will take up 9 bits in the resulting key.
    "key_piece": "0x400",// Conversion type purchase = 2
    // Apply this key piece to:
    "source_keys": ["campaignCounts"]
  },
  {
  // Purchase category shirts = 21 at a 7-bit offset, i.e. 21 << 7.
  // A 7-bit offset is needed because there are ~100 regions for the geo key,
  // which will take up 7 bits of space in the resulting key.
  "key_piece": "0xA80",
  // Apply this key piece to:
  "source_keys": ["geoValue", "nonMatchingIdsListedHereAreIgnored"]
  }
]

// Specify an amount of an abstract value which can be integers in [1, 2^16] to
// contribute to each key that is attached to aggregation keys in the order that
// they're generated.
Attribution-Reporting-Register-Aggregatable-Values:
[
  {
  // Privacy budget for each key is L1 / 2 = 2^15 (32768).
  // Conversion count was 1.
  // Scale the count to use the full budget allocated: 1 * 32768 = 32768.
     "campaignCounts": 32768,

  // Purchase price was $52.
  // Purchase values for the app range from $1 to $1,024 (integers only).
  // Scaling factor applied is 32768 / 1024 = 32.
  // For $52 purchase, scale the value by 32 ($52 * 32 = $1,664).
    "geoValue": 1664
  }
]

上面的示例生成了以下直方图贡献:

[
  // campaignCounts:
  {
    "key": "0x559", // = 0x159 | 0x400
    "value": 32768
  },
  // geoValue:
  {
    "key": "0xA85",  // = 0x5 | 0xA80
    "value": 1664
  }
]

可以反转缩放比例以获得正确的值,即应用的模除噪声:

L1 = 65536
trueCampaignCounts = campaignCounts / (L1 / 2)
trueGeoValue = geoValue / (L1 / 2) * 1024

差分隐私

该 API 的一个目标是拥有一个可以支持差分隐私汇总衡量的框架。这可以通过添加与 $ L1 $ 预算成比例的噪声来实现,例如拾取具有以下分布的噪声:

\[ Laplace(\frac{L1}{ε}) \]

注册优先级、归因和报告示例

此示例展示了一组用户互动,以及广告技术平台定义的归因来源和触发器优先级对归因报告的影响。在此示例中,我们做出如下假设:

  • 所有归因来源和触发器都由同一个广告技术平台为同一广告主注册。
  • 所有归因来源和触发器都发生在第一个事件报告期内(在发布商应用中首次展示广告后的 2 天内)。

请考虑用户做出以下行为的情况:

  1. 用户看到一则广告。广告技术平台向该 API 注册归因来源,优先级为 0(观看 1)。
  2. 用户看到一则广告,广告技术平台注册归因来源,优先级为 0(观看 2)。
  3. 用户点击一则广告,广告技术平台注册归因来源,优先级为 1(点击 1)。
  4. 用户在广告主应用中完成转化(转到着陆页)。广告技术平台向 API 注册触发器,优先级为 0(转化 1)。
    • 触发器注册后,API 先归因,然后再生成报告。
    • 可用的归因来源有 3 个:观看 1、观看 2 和点击 1。API 将此触发器归因于点击 1,因为它优先级最高且最新。
    • 观看 1 和观看 2 被舍弃,并且不再符合参与后续归因的条件。
  5. 用户在广告主应用中将一件商品添加到购物车,广告技术平台注册触发器,优先级为 1(转化 2)。
    • 点击 1 是唯一符合条件的归因来源。API 将此触发器归因于点击 1。
  6. 用户在广告主应用中将一件商品添加到购物车,广告技术平台注册触发器,优先级为 1(转化 3)。
    • 点击 1 是唯一符合条件的归因来源。API 将此触发器归因于点击 1。
  7. 用户在广告主应用中将一件商品添加到购物车,广告技术平台注册触发器,优先级为 1(转化 4)。
    • 点击 1 是唯一符合条件的归因来源。API 将此触发器归因于点击 1。
  8. 用户在广告主应用中购买商品,广告技术平台注册触发器,优先级为 2(转化 5)。
    • 点击 1 是唯一符合条件的归因来源。API 将此触发器归因于点击 1。

事件级报告具有以下特征:

  • 默认情况下,系统会在适用的报告期后发送前 3 个归因于点击的触发器和第一个归因于观看的触发器。
  • 在报告期内,如果存在以更高优先级注册的触发器,这些触发器优先于最新的触发器并取而代之。
  • 在前面的示例中,广告技术平台在 2 天的报告期后收到 3 份事件报告,分别与转化 2、转化 3 和转化 5 相关。
    • 5 个触发器全都归因于点击 1。默认情况下,API 会发送前 3 个触发器的报告:转化 1、转化 2 和转化 3。
    • 但是,转化 4 的优先级 (1) 高于转化 1 的优先级 (0)。因此,转化 4 的事件报告取代了转化 1 的事件报告被发送出去。
    • 此外,转化 5 的优先级 (2) 高于所有其他触发器。因此,转化 5 的事件报告取代了转化 4 的报告被发送出去。

可汇总报告具有以下特征:

  • 加密的可汇总报告在处理后(注册触发器几小时后)会立即发送到 Adtech。

    作为 Adtech,您可以根据可汇总报告中的未加密信息创建批次。这些信息包含在可汇总报告的 shared_info 字段中,其中包括时间戳和报告来源。您不能根据汇总键值对中的任何加密信息分批发送报告,但可以采用一些简单的策略,例如每天或每周分批发送报告。理想情况下,一个批次应包含至少 100 份报告。

  • 何时以及如何将可汇总报告分批并发送到汇总服务由广告技术平台决定。

  • 与事件级报告相比,加密的可汇总报告可以将更多触发器归因于某一个来源。

  • 在前面的示例中,发送了 5 份可汇总报告,每个已注册的触发器各一份。

扩展的调试报告

Attribution Reporting API 是一种相当复杂且无需跨应用标识符进行归因衡量的新方法。因此,我们很乐意引入一种过渡机制,以便在广告 ID 可用时了解归因报告的更多信息(例如,用户没有选择停用使用广告 ID 的个性化功能)。这样可以确保该 API 在发布期间可以被完全理解,有助于消除任何 bug,并更加轻松地与基于广告 ID 的替代方案进行比较。

来源和触发器注册都将接受由广告技术平台填充的新的 64 位 debug_key 字段。在事件级报告和汇总报告中,source_debug_keytrigger_debug_key 将保持不变。

如果创建同时包含来源和和触发器调试键的报告,则以有限的延迟时间向 .well-known/attribution-reporting/debug/report-event-attribution 端点发送调试报告副本。调试报告与普通报告相同,包含两个调试键字段。通过在这两个报告中包含这些键,可将常规报告关联到单独的调试报告流。

  • 对于事件级报告:
    • 调试报告副本会在有限时间内发送,因此不受可用触发器的限制约束,这让广告技术平台能够了解这些限制对事件级报告的影响。
    • 与错误触发器事件相关联的事件级报告将不包含 trigger_debug_key。这样一来,广告技术平台就可以更清楚地了解 API 中应用噪声的方式。
  • 对于可汇总报告:

    • 只有在同时设置了 source_debug_keytrigger_debug_key 的情况下,我们才会支持包含解密载荷的新 debug_cleartext_payload 字段。
  • 如需详细了解如何使用“应用到网站”和“网站到应用”衡量来调试报告,请参阅归因报告:跨应用和跨网站衡量

如何使用调试报告

如果发生转化(根据您现有的衡量系统),并且收到该转化的调试报告,则表示触发器已成功注册。

对于每个调试归因报告,请检查您是否收到与两个调试键相匹配的常规归因报告。

多种原因可能会导致数据不一致。

运行正常:

  • 可保护隐私的 API 行为:
    • 用户达到了报告速率限制 — 这会导致该时间段内的所有后续报告都无法发送;或者来源因待处理目标限制而被移除。
    • 对于事件级报告:报告会受随机响应(噪声)影响,并被限制,或者您可能会收到随机报告。
    • 对于事件级报告:已达到 3 个(针对点击)或 1 个(针对数据视图)报告的限制,后续报告没有明确的优先级设置,或者优先级低于现有报告。
    • 已超出可汇总报告的贡献限制。
  • 广告技术平台定义的业务逻辑:
    • 通过过滤条件或优先级规则滤除触发器。
  • 时间延迟或与网络可用时的互动(例如,用户长时间关闭设备)。

意外原因:

  • 实施问题:
    • 来源标头配置错误。
    • 触发器标头配置错误。
    • 其他配置问题。
  • 设备或网络问题:
    • 因网络状况而发生故障。
    • 来源或触发器注册响应未到达客户端。
    • API bug。

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

Attribution Reporting API 正在开发中。此外,我们还在探索未来可能会推出的功能,例如非最终点击归因模型和跨设备衡量用例。

此外,我们希望就以下几个问题向社区征求反馈:

  1. 我们计划允许多个广告技术平台注册归因来源和触发器,以便实现第三方衡量。在我们当前的方案中,只有发起 API 调用的广告技术平台可以指定第三方广告技术平台列表。为了简化我们的 API 设计,我们可以改为仅指定下一个广告技术平台,来允许广告技术平台进行菊花链重定向。
  2. 对于归因来源注册,我们正在评估提议的第三方和重定向设计(包括自归因网络的设计)是否可行。特别是,我们想知道您是否需要清楚看到重定向路径中的每个人。
  3. 注册归因来源时,广告技术平台只能指定一个应用目标。我们想知道这是否适合您的用例。
  4. 注册归因来源时,您可以设置过期时间,它与回溯期等效。可接受的最短过期时间为归因来源发生之日起的 2 天。否存在此工作流程会发生中断的任何用例?
  5. 是否具有需要 API 针对已验证安装发送报告的用例?这些报告会计入广告技术平台各自的速率限制。
  6. 您在将 InputEvent 从应用传递到广告技术平台以进行源代码注册时,是否遇到任何困难?