Protected Audience API：开发者指南

开发者指南，介绍了如何在不使用跨网站第三方跟踪的情况下，通过设备端广告竞价投放再营销和自定义受众群体。

如果您刚开始接触 Protected Audience API，请参阅 Protected Audience API 概览，了解该 API 的简要说明。

本博文面向开发者，是实验性 Protected Audience API 最新迭代的技术参考。我们提供基本 Protected Audience API 部署的演示，以及广告买方和卖方的 API 参考文档。

实现状态

如需接收有关 API 状态变更的通知，请加入开发者邮寄名单。

什么是 Protected Audience API？

Protected Audience API 是一个 Privacy Sandbox API，旨在满足再营销和自定义受众群体用例的需求，第三方无法使用它来跟踪用户跨网站的用户浏览行为。该 API 支持浏览器进行设备端竞价，以便为用户之前访问过的网站选择相关广告。

Protected Audience API 是要在 Chromium 中通过 TURTLEDOVE 提案系列实现的第一个实验。

试用 Protected Audience API

可用的 API 参考文档

本文档简要介绍了 Protected Audience API。如果您需要特定的 API 方法和参数，请执行以下操作：

您还可以阅读 Protected Audience API 广告竞价延迟时间最佳做法。

Protected Audience API 演示

有关在广告客户和发布商网站上进行基本 Protected Audience API 部署的演示，请访问 protected-audience-demo.web.app/。

观看此端到端部署，了解 Protected Audience API 演示代码的工作原理以及如何使用 Chrome 开发者工具进行调试。

使用 chrome://flags 或功能标志进行测试

您可以在桌面版 Chrome Beta 版 101.0.4951.26 及更高版本中为单个用户测试 Protected Audience API：

在 iframe 或围栏框架中呈现广告

广告可以在 <iframe> 或 <fencedframe> 中呈现，具体取决于设置的标记。

如需使用 <fencedframe> 呈现广告，请执行以下操作：

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames

如需使用 <iframe> 呈现广告，请执行以下操作：

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames

添加 BiddingAndScoringDebugReportingAPI 标志以启用临时调试损失/成功报告方法。

支持的功能

Chromium 中功能标志背后的 Protected Audience API 是第一个对 Protected Audience API 功能进行测试的实验：

  • 兴趣组：由浏览器存储，具有关联的元数据，用于配置广告出价和呈现。
  • 买方（DSP 或广告主）的设备端出价：基于存储的兴趣群体和来自卖方的信号。
  • 卖方（SSP 或发布商）在设备端选择广告选择：基于竞价出价和买方的元数据。
  • 在暂时放宽的围栏框架版本中呈现广告：允许进行网络访问和日志记录，以便呈现广告。

如需详细了解功能支持和限制条件，请参阅 Protected Audience API 说明文档。

兴趣群体权限

Protected Audience API 的当前实现方案默认允许从网页中的任何位置（甚至从跨网域 iframe）调用 joinAdInterestGroup()。

将来，一旦网站所有者有时间更新其跨网域 iframe 权限政策，我们便会禁止从跨网域 iframe 进行调用。

键值对服务

为了支持 Protected Audience API 广告竞价，浏览器可以访问键值对服务来检索支持 Protected Audience API 广告竞价的实时信息。此信息可通过多种方式使用：

  • 买方可能希望计算广告系列的剩余预算。
  • 卖方可能需要检查广告素材是否符合发布商政策。

Protected Audience API 键值对服务代码现已发布。如需了解状态更新，请参阅公告博文。

对于初始测试，引入了“自带服务器”模型。从长远来看，广告技术平台需要使用在可信执行环境中运行的开源 Protected Audience API 键值对服务。

如需了解时间表更新，请参阅 Protected Audience API 服务博文。在过渡之前，我们会为开发者提供充分的通知，让他们开始进行测试和采用。

检测功能支持情况

使用该 API 之前，请检查浏览器是否支持该 API，以及该 API 是否可在文档中使用：

'joinAdInterestGroup' in navigator &&
  document.featurePolicy.allowsFeature('join-ad-interest-group') &&
  document.featurePolicy.allowsFeature('run-ad-auction') ?
  console.log('navigator.joinAdInterestGroup() is supported on this page') :
  console.log('navigator.joinAdInterestGroup() is not supported on this page');

Protected Audience API 的工作原理是什么？

在本例中，用户浏览了一家定制自行车制造商的网站，稍后访问了一个新闻网站，看到了这家自行车制造商生产的一款新自行车的广告。

随着实现过程中的不断完善，Protected Audience API 的功能将逐步添加。

1. 用户访问广告客户的网站

一个人在笔记本电脑上的浏览器中访问了定制自行车制造商的网站。

假设某位用户访问了定制自行车制造商（在此示例中为广告客户）的网站，并在手工钢自行车的产品页面上停留了一段时间。这为自行车制造商提供了再营销机会。

2. 要求用户浏览器添加兴趣群体

用户在笔记本电脑上打开浏览器并访问某个网站。浏览器中正在运行用于加入广告兴趣群体的 JavaScript 代码。

广告主的需求方平台 (DSP)（或广告主本身）会调用 navigator.joinAdInterestGroup()，要求浏览器将兴趣群体添加到浏览器所属的群组列表中。

在此示例中，群组名为 custom-bikes，所有者为 dsp.example。兴趣群体所有者（在本例中为 DSP）将是 Protected Audience API 广告竞价中的买方。兴趣组成员资格由浏览器存储在用户设备上，不会与浏览器供应商或其他任何人共享。

为兴趣群体指定广告

ads 和 adComponents 对象包含广告素材的网址，以及可在出价时使用的任意元数据（可选）。例如：

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

买方如何出价？

对于浏览器所属的每个兴趣群体（如果相应兴趣群体的所有者受邀出价），系统会调用 generateBid()。

阅读 generatedBid() 开发者文档。

3. 用户访问销售广告空间的网站

一个人在笔记本电脑上的浏览器中访问新闻网站。网站包含空广告位。

之后，用户访问了销售广告空间的网站，在本例中为新闻网站。该网站包含广告资源，通过实时出价以编程方式销售这些广告资源。

4. 广告竞价是在浏览器中进行的

一个人在笔记本电脑上的浏览器中查看新闻网站。系统会运行 Protected Audience API 广告竞价，以挑选广告填充可用的广告空间。

广告竞价可能由发布商的供应方提供商 (SSP) 或发布商本身进行。竞价的目的是为当前页面上的单个可用广告位选择最合适的广告。竞价时会考虑浏览器所属的兴趣群体，以及来自键值对服务的广告空间买方和卖方的数据。

5. 卖方和参与的买方从键值对服务请求实时数据

用户在笔记本电脑上的浏览器中查看新闻网站。正在进行使用 Protected Audience API 的广告竞价，参与者从键值对服务获取数据。

在广告竞价期间，卖方可以通过向特定广告素材的键值对服务发出请求，请求有关这些广告素材的实时数据。卖方可以在 runAdAuction() 期间通过 trustedScoringSignalsUrl 属性请求此信息，以及竞价中所有兴趣群体的 ads 和 adComponents 字段中所有条目的 renderUrl 属性的键。

买方可以使用传递给 navigator.joinAdInterestGroup() 的兴趣群体参数的 trustedBiddingSignalsUrl 和 trustedBiddingSignalsKeys 属性，从其键值对服务请求实时数据。

调用 runAdAuction() 时，浏览器会向每个广告买方的可信服务器发出请求。请求的网址可能如下所示：

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
  • 基准网址来自 trustedBiddingSignalsUrl。
  • hostname 由浏览器提供。
  • keys 值取自 trustedBiddingSignalsKeys。

该请求的响应是一个 JSON 对象，为每个键提供值。

6. 胜出的广告进行展示

一个人在笔记本电脑上的浏览器中查看新闻网站。在安全的围栏框架中，展示自行车半价优惠的广告。

当竞价配置中的 resolveToConfig 标志设置为 true 时，runAdAuction() 返回的 promise 会解析为围栏框架配置对象 (FencedFrameConfig)。围栏框架使用框架配置将框架导航到胜出的广告，但广告的网址对框架嵌入器不可见。

从 M114 开始，围栏框架配置对象可用。如需详细了解 FencedFrameConfig 对象，请参阅 Chrome 博文。

7. 系统会报告竞价结果

长期计划是允许浏览器使用 Private Aggregation API 报告卖方和买方的竞价结果。

作为临时的事件级报告机制，为卖方实现 reportResult() 并为胜出的出价方实现 reportWin() 的代码可以调用 sendReportTo() 函数。这只需要一个参数：一个字符串，表示竞价完成后提取的网址，它对要报告的事件级信息进行编码。

8. 报告了一次广告点击

一个用户在新闻网站上点击嵌入了围栏框架的自行车广告。报告数据会发送给卖方和买方。

系统会报告在围栏框架中呈现的广告获得的点击。如需详细了解可能的工作原理，请参阅围栏框架广告报告。

Protected Audience API 广告竞价的各个阶段概览
此图展示了 Protected Audience API 竞价的各个阶段。

Protected Audience API 与 TURTLEDOVE 有何区别？

Protected Audience API 是第一个在 Chromium 中通过 TURTLEDOVE 提案系列实现的实验。

Protected Audience API 遵循 TURTLEDOVE 的概要原则。有些在线广告会面向曾与广告客户或广告网络互动过且可能感兴趣的用户展示广告。以前，广告客户只要在特定用户的浏览行为中辨认出他们，就可以通过这种方法识别，这是当今网络的核心隐私问题。

TURTLEDOVE 的工作旨在提供一个新的 API 来解决此用例，同时提供一些重要的隐私保护措施：

  • 浏览器（而不是广告主）保存的是广告主认为用户感兴趣的内容的相关信息。
  • 广告主可以根据兴趣投放广告，但无法将这种兴趣与用户的其他相关信息（特别是用户的身份或正在访问的网页）相结合。

Protected Audience API 依托于 TURTLEDOVE 和一系列相关的修改提案，旨在更好地为可能会使用该 API 的开发者提供服务：

  • 在 SPARROW 中：Criteo 提议添加在可信执行环境 (TEE) 中运行的“Gatekeeper”服务模型。Protected Audience API 对 TEE 的使用较为有限，用于实时数据查询和汇总报告。
  • NextRoll 的 TERN 和 Magnite 的 PARRROT 提案描述了买方和卖方在设备端竞价中所扮演的不同角色。Protected Audience API 的广告出价/评分流程就是以此为基础。
  • RTB House 的基于结果和产品级的 TURTLEDOVE 修改改进了设备端竞价的匿名性模型和个性化功能
  • PARAKEET 是 Microsoft 针对类似 TURTLEDOVE 的广告服务提出的提案，该服务依赖于在浏览器和广告技术提供商之间的 TEE 中运行的代理服务器来对广告请求进行匿名化处理并强制执行隐私权属性。Protected Audience API 未采用此代理模型。我们将使适用于 PARAKEET 的 JavaScript API 和 Protected Audience API 保持一致，以便为未来进一步组合这两个提案的最佳功能提供支持。

Protected Audience API 尚不能阻止网站的广告网络学习用户会看到哪些广告。我们预计会不断修改该 API，使其更加私密。

Topics API 可以与 Protected Audience API 搭配使用吗？

是的。由 Topics API 提供的当前用户观察到的主题可用作卖方或出价工具的上下文信息。主题可包含以下属性中：

  • auctionSignals，是传递给 navigator.runAdAuction() 的竞价配置对象的属性
  • userBiddingSignals 是传递给 navigator.joinAdInterestGroup() 的兴趣群体配置对象的属性

可用的浏览器配置

用户可以通过在 chrome://settings/adPrivacy 中启用或停用顶层设置来调整自己在 Chrome 中参与 Privacy Sandbox 试用的计划。

在初始测试期间，用户可以通过此高级 Privacy Sandbox 设置来选择停用 Protected Audience API。Chrome 计划允许用户查看和管理他们被添加到他们访问过的所有网站上的兴趣群体列表。与 Privacy Sandbox 技术本身一样，用户设置可能会随着用户、监管机构和其他方的反馈而变化。

我们会继续根据测试和反馈更新 Chrome 中的可用设置。 未来，我们计划提供更精细的设置来管理 Protected Audience API 和相关数据。

当用户在无痕模式下浏览时，API 调用方将无法访问群组成员资格，并且当用户清除其网站数据时，其成员资格会被移除。

浏览器是否会缓存 Protected Audience Worklet？

浏览器会缓存包含 Protected Audience 工作单元（买方的出价生成和报告工作单元，以及卖方的广告评分和报告工作单元）的资源。您可以使用 Cache-Control 标头控制缓存行为。

互动和分享反馈

获取支持

如需咨询问题并获取实现、演示或文档方面的支持，请执行以下操作：

如有关于如何使用 Protected Audience API 满足您的需求的更多常见问题，请在 API 代码库上提交问题。 您还可以在 W3C 的 Improving Web Advertising Business Group 中讨论行业应用场景。

您可以使用 Privacy Sandbox 反馈表单在公共论坛之外私下与 Chrome 团队分享反馈。

停用

想选择停用 Protected Audience API？了解如何以网站所有者或个人用户身份阻止对 Protected Audience API 的访问。

获取更新