Protected Audience API：开发者指南

开发者指南：如何通过设备端广告竞价投放再营销广告和自定义受众群体定位广告，而无需进行跨网站第三方跟踪。

如果您是 Protected Audience API 的新手，请阅读 Protected Audience API 概览，了解有关该 API 的大致说明。

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

实现状态

• Protected Audience API 提案现已正式发布。提出问题并跟进讨论。
• Protected Audience API 待处理功能的状态详细介绍了 Protected Audience API API 和功能的变化和增强。
• 闪烁状态
• Protected Audience API Chrome 平台状态：专门针对 Chrome 上的 Protected Audience API。
• 广告 API Chrome 平台状态：一组用于促进广告投放的 API：Protected Audience API、Topics、Fenced Frames 和 Attribution Reporting。

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

什么是 Protected Audience API？

Protected Audience API 是一项 Privacy Sandbox API，旨在满足再营销和自定义受众群体的使用情形，并且经过精心设计，第三方无法使用它来跟踪用户的跨网站浏览行为。该 API 可让浏览器在设备端开展竞价，以便为用户之前访问过的网站选择相关广告。

Protected Audience API 是在 TURTLEDOVE 系列提案中首次在 Chromium 中实现的实验。

试用 Protected Audience API

可用的 API 参考文档

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

• joinAdInterestGroup() 和 generateBid() 的买方指南。
• Protected Audience API 卖家指南 runAdAuction()
• 买家指南：reportWin()；卖家指南：reportResult()
• 排查 Protected Audience API 问题

您还可以参阅 Protected Audience API 广告竞价延迟时间最佳实践。

Protected Audience API 演示

如需了解如何在广告客户网站和发布商网站上部署基本的 Protected Audience API，请访问 protected-audience-demo.web.app/。

测试此 API

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

• 启用 chrome://settings/adPrivacy 下的所有广告隐私权 API。
• 通过命令行设置标志。 您可以在 Chromium 代码搜索中找到可用的 Protected Audience API 标志的完整列表。

在 iframe 或 fenced frame 中呈现广告

广告可以以 <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 或发布商）在设备上选择广告：根据买方的竞价和元数据。
• 在暂时放宽限制的 Fenced Frames 版本中呈现广告：允许网络访问和日志记录以进行广告呈现。

如需详细了解功能支持和限制，请参阅 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. 系统要求用户的浏览器添加兴趣群体

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

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

• 阅读 Protected Audience API 说明：浏览器记录兴趣群体。
• 阅读 API 指南：买方和 DSP，了解如何joinAdInterestGroup() 和生成出价。

为兴趣群体指定广告

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

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

买家如何出价？

如果兴趣群体所有者受邀参与出价，则会针对浏览器所属的每个兴趣群体调用 generateBid()。

阅读 generatedBid() 开发者文档。

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

之后，用户访问一个出售广告空间的网站（在本例中为新闻网站）。该网站拥有广告资源，并通过实时出价以程序化方式出售这些资源。

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

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

• 阅读 Protected Audience API 说明文档：卖方运行设备端竞价
• 阅读 API 指南：卖家可以详细了解 runAdAuction() 和广告竞价延迟时间最佳实践。

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

在广告竞价期间，卖方可以通过向其键值对服务发出请求，来请求有关特定广告素材的实时数据。卖家可以在 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 对象，其中包含每个键的值。

• 阅读 Protected Audience API 说明：从 Protected Audience API 键值对服务中提取实时数据。
• 请参阅将 Protected Audience API 键值服务开源。

6. 展示胜出的广告

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

从 M114 开始提供围栏框架配置对象。如需详细了解 FencedFrameConfig 对象，请参阅这篇 Chrome 博客文章。

• 阅读 Protected Audience API 说明：浏览器呈现胜出的广告

7. 报告竞价结果

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

作为一种临时的事件级报告机制，为卖方实现 reportResult() 的代码和为中标方实现 reportWin() 的代码可以调用 sendReportTo() 函数。此函数接受一个实参：一个字符串，表示竞价结束后提取的网址，其中包含要报告的事件级信息。

• 阅读 API 指南：了解卖家和买家报告

8. 报告了广告点击

系统会报告在围栏框架中呈现的广告的点击。如需详细了解此功能可能的工作方式，请参阅受限框架广告报告。

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 House 对 TURTLEDOVE 进行了基于效果和产品级的修改，从而改进了设备端竞价的匿名性模型和个性化功能
• PARAKEET 是 Microsoft 提出的类似 TURTLEDOVE 的广告服务，它依赖于在浏览器和广告技术提供商之间运行的 TEE 中的代理服务器，以匿名化广告请求并强制执行隐私属性。Protected Audience API 尚未采用此代理模式。我们将 PARAKEET 和 Protected Audience API 的 JavaScript API 保持一致，以便在未来进一步结合这两个提案的最佳功能。

Protected Audience API 尚无法阻止网站的广告联盟了解用户看到了哪些广告。我们预计会随着时间的推移修改该 API，使其更加私密。

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

可以。由 Topics API 提供的当前用户的观测主题可被卖家或出价方用作情境信息。主题可以包含在以下属性中：

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

可用的浏览器配置

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

在初始测试期间，用户可以使用此高级别 Privacy Sandbox 设置来选择停用 Protected Audience API。Chrome 计划允许用户查看和管理他们被添加到其中的兴趣群体名单，这些兴趣群体来自他们访问过的网站。与 Privacy Sandbox 技术本身一样，用户设置可能会根据用户、监管机构和其他方的反馈而不断改进。

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

当用户以无痕模式浏览时，API 调用方无法访问群组成员资格；当用户清除网站数据时，系统会移除成员资格。

Protected Audience worklet 是否由浏览器缓存？

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

互动并分享反馈

获取支持

如需就实现、演示或文档提出问题并获得支持，请执行以下操作：

• GitHub：阅读解释器，提出问题并关注讨论。
• 演示：在演示代码库中提出问题。
• Chrome 实现：如果 Chrome 在实现 Protected Audience API 时存在 bug 或问题，您可以查看现有问题或提出新问题。

如果您有关于如何使用 Protected Audience API 满足需求的更一般性问题，请在 API 代码库中提交问题。 您还可以在 W3C 的 Improving Web Advertising Business Group 中讨论行业用例。

使用 Privacy Sandbox 反馈表单，在公开论坛之外私下与 Chrome 团队分享反馈。

选择停用

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

获取更新

• 如需接收有关 API 状态变更的通知，请加入面向开发者的邮寄名单。
• 如需密切关注有关该 API 的所有正在进行的讨论，请点击 GitHub 上的 API 页面中的关注按钮。为此，您需要拥有或创建 GitHub 账号。
• 如需全面了解 Privacy Sandbox 的最新动态，请订阅 RSS Feed [Privacy Sandbox 的进展]。
• 加入 Protected Audience API 的定期通话（每隔一周举行一次）。欢迎所有人加入。如需参与，请先加入 WICG。您可以积极参与，也可以只是旁听！