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 提案系列。

试用 Protected Audience API

可用的 API 参考文档

本文档简要介绍了 Protected Audience API。如果您要查找特定的 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： 桌面设备：

在 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。兴趣组所有者（在本例中为需求方平台）将成为买方 在 Protected Audience API 广告竞价中胜出。兴趣组成员资格由浏览器存储， 并且不会与浏览器供应商或其他任何人共享。

。

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

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

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

买方如何出价？

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

阅读 generatedBid() 开发者文档。

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

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

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

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

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

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

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

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

在广告竞价期间，卖方可以请求获取有关特定广告的实时数据 广告素材，方法是向其键值对服务发出请求。 卖家可以在 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 对象，该对象为每个 键。

。

6. 展示胜出的广告

一个人在笔记本电脑上的浏览器中查看新闻网站。广告 以八折的价格出售自行车。

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

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

7. 系统会将竞价结果

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

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

8. 报告一次广告点击

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

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

<ph type="x-smartling-placeholder">
</ph> <ph type="x-smartling-placeholder"></ph> Protected Audience API 广告竞价每个阶段的概览
此图概述了 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 标头来控制缓存行为。

互动和分享反馈

获取支持

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

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

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

选择停用

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

获取更新