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 是 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 的以下功能：

  • 兴趣组：由浏览器存储，并包含用于配置广告出价和呈现的相关元数据。
  • 买方（需求方平台或广告客户）在设备端出价：根据存储的兴趣组和卖方提供的信号。
  • 卖方（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 是在 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 中启用或停用顶层设置来调整参与 Privacy Sandbox 在 Chrome 中的试用活动。

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

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

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

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

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

互动和分享反馈

获取支持

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

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

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

选择停用界面

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

获取更新