Protected Audience API：开发者指南

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

更新：FLEDGE 已重命名为 Protected Audience API。如需详细了解更名，请参阅这篇博文。

要点：Privacy Sandbox Relevance and Measurement 源试用已于 2023 年 9 月 20 日结束，相关 API 现已面向 99% 的 Chrome 用户提供，源试用注册现已结束。如需了解已启用每个 API 的用户所占的百分比，请参阅 Chrome 状态图表。

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

本博文供开发者参考， 实验性 Protected Audience API 的近期迭代。基本组件的演示 Protected Audience API 部署可用， 广告买方和卖方的 API 参考文档。

实现状态

• The Protected Audience API proposal is now moving to general availability. Raise questions and follow discussion.
• Protected Audience API status of pending capabilities details changes and enhancements to the Protected Audience API API and features.
• Blink status
• Protected Audience API Chrome platform status: Specific to the Protected Audience API on Chrome.
• Ads API Chrome platform status: A collection of APIs to facilitate advertising: Protected Audience API, Topics, Fenced Frames and Attribution Reporting.

To be notified of status changes in the API, join the mailing list for developers.

什么是 Protected Audience API？

Protected Audience API 是一种 Privacy Sandbox API，旨在 再营销和自定义受众群体使用 以便第三方无法使用它来跟踪用户 跨网站的浏览行为。该 API 通过 来为用户之前访问过的网站选择相关的广告。

Protected Audience API 是 TURTLEDOVE 提案系列。

试用 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/。

<ph type="x-smartling-placeholder">

</ph>

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

测试此 API

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

• 启用 chrome://settings/adPrivacy 下的所有广告隐私权 API。
• 通过命令行设置标志。 如需查看可用 Protected Audience API 标志的完整列表，请参阅 Chromium 代码搜索。

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

广告可以通过 <iframe> 或 <fencedframe>，具体取决于哪个 标志。

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

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

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

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

添加 BiddingAndScoringDebugReportingAPI 标志即可启用 临时调试失败/胜出报告方法。

注意：这是用于早期测试的 Protected Audience API 开发中版本。不应 视为已完成或表示最终实现。Protected Audience API 进度 和状态将在 WICG 定期会议上讨论。 Privacy Sandbox 时间表提供了 Protected Audience API 和其他 Privacy Sandbox API 的实现时间表。

支持的功能

在 Chromium 中，Protected Audience API 背后的功能标志是首个用于测试 Protected Audience API 的以下功能：

• 兴趣群体：由浏览器存储，并提供关联的元数据 配置广告出价和呈现。
• 买方（需求方平台或广告客户）在设备端出价：基于存储的 兴趣群体以及卖方提供的信号。
• 卖方（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');

注意：当前页面上的功能支持并不保证某个 API 可用。 用户可能已通过浏览器设置停用了 API，或者可能还有其他 来阻止 API 使用。为了保护用户 因此无法以编程方式进行检查。

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

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

警告：本博文中描述的部分功能并未实现（或完全 已在 Chrome 中测试的 Protected Audience API 版本中实现）。 使用功能标志进行测试：介绍了目前有哪些 Protected Audience API 功能 可在 Chrome 中测试。

随着实施工作的不断推进，Protected Audience API 的功能将陆续添加。

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

假设某位用户访问了一家定制自行车制造商（广告客户）的网站 并在产品页面上花时间浏览了一款手工钢材 自行车。这样自行车制造商就可以 再营销优化建议。

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

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

在此示例中，群组名为 custom-bikes，所有者为 dsp.example。兴趣组所有者（在本例中为需求方平台）将成为买方 在 Protected Audience API 广告竞价中胜出。兴趣组成员资格由浏览器存储， 并且不会与浏览器供应商或其他任何人共享。

• 阅读 Protected Audience API 说明文档：浏览器记录兴趣组。
• 阅读 API 指南：买方和需求方平台；了解如何 joinAdInterestGroup() 并生成出价。

。

注意：joinAdInterestGroup() 的调用上下文的来源必须与 兴趣群体所有者的来源。 必须通过兴趣组所有者拥有的 iframe（例如，从 DSP）调用 joinAdInterestGroup()。如果当前文档的来源与兴趣群体所有者相同（例如，有自己的兴趣群体的网站），则不需要使用 iframe。

针对某一兴趣群体指定广告

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

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

买方如何出价？

针对浏览器所属的每个兴趣群体都调用 generateBid() — 前提是相应兴趣群体的所有者受邀参与出价。

阅读 generatedBid() 开发者文档。

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

后来，该用户访问了一个销售广告空间的网站，在本例中为一个新闻 网站。该网站以程序化方式销售广告资源 实时出价。

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

广告竞价可能由发布商的供应方提供商开展 或发布商本身竞价的目的是 最适合当前页面上的单个可用广告位的广告。通过 会考虑浏览器所属的兴趣群体， 以及广告空间买方和卖方的 键值对服务。

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

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

在广告竞价期间，卖方可以请求获取有关特定广告的实时数据 广告素材，方法是向其键值对服务发出请求。 卖家可以在 runAdAuction()（按 trustedScoringSignalsUrl 属性划分）、 以及 ads 中所有条目的 renderUrl 属性中的键 和 adComponents 字段。

买方可以使用 trustedBiddingSignalsUrl 和 trustedBiddingSignalsKeys 属性 传递给 navigator.joinAdInterestGroup() 的兴趣群体参数。

调用 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 键值对服务开源。

。

要点：在测试 Protected Audience API 的初始实验阶段时， trustedBiddingSignalsUrl必须与兴趣群体同源 所有者。如需了解详情，请参阅自带服务器。

6. 展示胜出的广告

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

注意：仅当竞价配置中的 resolveToConfig 标志设置为 true 时，系统才会返回 FencedFrameConfig 对象。如果该标志未设置或者为 false，则返回的不透明 URN 只能在 iframe 中呈现。

从 M114 开始提供围栏帧配置对象。如需详细了解 FencedFrameConfig 对象，请参阅 Chrome 博文。

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

7. 系统会将竞价结果

我们的长期计划是让浏览器报告 使用 Private Aggregation API 进行集成。

作为一种临时的事件级报告机制，用于实施 reportResult()（卖方）和 reportWin()（胜出出价方）可以 调用 sendReportTo() 函数。此方法接受一个参数：字符串 表示在竞价完成后获取的网址，该网址会将 事件级信息。

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

8. 报告一次广告点击

系统会报告一次在围栏框架中呈现的广告获得的点击。要详细了解 具体运作方式，请参阅围栏框架广告报告。

---

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder"></ph>

此图概述了 Protected Audience API 竞价的每个阶段。

Protected Audience API 与 TURTLEDOVE 之间有何区别？

Protected Audience API 是 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 中试用 Privacy Sandbox： 在“设置”中启用或停用顶级设置 chrome://settings/adPrivacy。

在初始测试期间，用户可以使用此高级隐私设置 用于选择停用 Protected Audience API 的沙盒设置。Chrome 计划允许用户查看和 管理整个网络上将他们添加到的兴趣群体列表 。与 Privacy Sandbox 技术本身一样， 用户设置可能会随着用户、监管机构和其他人的反馈而不断变化。

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

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

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

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

互动和分享反馈

获取支持

提出问题并获得有关实施、演示或 文档：

• GitHub：阅读 explainer， 提出问题并关注讨论。
• 演示：在演示代码库中提出问题。
• 开发者支持：提出问题并加入 Privacy Sandbox 开发者支持 代码库。 为 Protected Audience API 选择问题模板。
• Chrome 实现：用于报告与 Chrome 实现 您可以查看现有问题 或提出新问题。

如需了解使用 Protected Audience API 来满足您需求的更多常规问题， 在 API 代码库中提交问题。 您还可以在 W3C 的 Improving Web Advertising Business Group。

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

选择停用

想停用 Protected Audience API？了解如何 禁止访问 Protected Audience API， 以网站所有者或个人用户的身份登录。

获取更新

• 如需 API 状态变更通知，请加入 开发者邮寄名单。
• 要密切关注目前正在进行的有关 API 的所有讨论，请点击 API 页面上观看按钮， GitHub。这要求您拥有或创建一个 GitHub 账号。
• 如需了解 Privacy Sandbox 的总体动态，请订阅 RSS Feed [Privacy Sandbox 取得的进展]。
• 加入 Protected Audience API 的预定调用 （每第二周）。欢迎所有人加入，积极参与、 首先请务必加入 WICG。您 可以积极参与或只是收听！