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 来跟踪用户的跨网站浏览行为。该 API 支持浏览器在设备端开展竞价，以便为用户之前访问过的网站选择相关广告。

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

试用 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 开发者工具进行调试。

测试此 API

您可以在桌面设备上使用 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 当前实现的默认设置是允许从网页中的任何位置调用 joinAdInterestGroup()，即使是从跨网域 iframe 调用也是如此。

未来，在网站所有者有时间更新其跨网域 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 是 TURTLEDOVE 系列提案中在 Chromium 中实现的第一个实验。

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 广告交易平台的基于结果和产品级 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 的访问。

获取更新