此页面由 Cloud Translation API 翻译。

FLEDGE API 开发者指南

本文的适用对象

本文是对实验性 Protected Audience API 当前迭代的技术参考。

Protected Audience API 是一种技术性更弱的提案概览，还有一个术语库。
Protected Audience 演示：演示基本 FLEDGE 部署。
Protected Audience 演示视频解释了演示代码的工作原理，并展示了如何使用 Chrome 开发者工具进行 Protected Audience 调试。

什么是 Protected Audience？

Protected Audience API 是一项 Privacy Sandbox 提案，旨在再营销和自定义受众群体用例，旨在确保这些用例无法用于跟踪用户跨网站浏览行为。该 API 通过来为用户之前访问过的网站选择相关的广告。

Protected Audience 是 TURTLEDOVE 提案系列。

下图简要介绍了 FLEDGE 生命周期：

如何试用 Protected Audience？

Protected Audience 演示

有关跨广告客户和发布商网站进行基本 Protected Audience 部署的演示，请访问： protected-audience-demo.web.app.

演示视频解释了演示代码的工作原理，并展示了如何使用 Chrome 开发者工具进行 Protected Audience 调试。

参与 Protected Audience 源试用

已完成 Privacy Sandbox 相关性和效果衡量源试用适用于桌面设备上的 Chrome Beta 101.0.4951.26 及更高版本，适用于 Protected Audience。主题和 Attribution Reporting API。

要参与试用，请注册源试用令牌。

成功注册试用后，您便可以在网页上试用 Protected Audience JavaScript API （提供有效试用令牌）：例如，请求浏览器加入一个或多个兴趣群体，然后开展广告竞价以选择并展示广告。

Protected Audience 演示提供了端到端 Protected Audience 部署的基本示例。

为您要运行 Protected Audience API 代码的每个网页提供试用令牌：

作为 <head> 中的元标记：

<meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
作为 HTTP 标头：

Origin-Trial: TOKEN_GOES_HERE

以编程方式提供令牌：

const otMeta = document.createElement('meta');
otMeta.httpEquiv = 'origin-trial';
otMeta.content = 'TOKEN_GOES_HERE';
document.head.append(otMeta);

运行 Protected Audience 代码的 iframe（例如 navigator.joinAdInterestGroup()）调用）将需要提供与其源匹配的令牌。

提议的首个 Protected Audience 源试用详情详细介绍了首次试用的目标，并说明了支持的功能。

测试此 API

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

通过启用 chrome://settings/adPrivacy 下的所有广告隐私权 API
通过命令行设置标志。

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

广告可以在 <iframe> 或 <fencedframe> 中呈现，具体取决于设置的标志。

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

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

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

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

添加 BiddingAndScoringDebugReportingAPI 标志，以启用临时调试损失/胜出报告方法。

使用 flag 运行 Chromium 解释了在运行 Chrome 和其他基于 Chromium 的浏览器时如何从命令设置标记行。Protected Audience 标志的完整列表可从 Chromium 代码搜索。

最新版 Chrome 支持哪些功能？

Protected Audience 率先在 Chromium 中的功能标志后面提供实验来测试 Protected Audience 提案的以下功能：

兴趣组：由浏览器存储，其中包含用于配置广告出价的关联元数据和渲染。
买方（需求方平台或广告客户）在设备端出价：根据存储的兴趣群体和信号。
卖方（SSP 或发布商）在设备端选择广告：根据竞价出价和来自买方的元数据。
在暂时放宽的围栏框架中呈现广告：可以通过网络访问和允许广告呈现。

API 说明文档提供了更多详细信息功能支持和限制条件等信息。

兴趣群体权限

Protected Audience 当前实现中的默认设置是允许从joinAdInterestGroup() 网页中的任意位置，甚至从跨网域 iframe 中也是如此。以后，只要网站所有者有时间调整跨网域 iframe 权限政策，计划是禁止从实现跨网域 iframe，如铺垫内容所述

键值对服务

在 Protected Audience 广告竞价中，浏览器可以访问键值对服务可返回简单的键值对来向广告买方提供信息，广告系列预算。Protected Audience 提案的授权书此服务器“不执行事件级日志记录，也不会根据这些请求”。

Protected Audience 键值对服务代码现已在 Privacy Sandbox GitHub 代码库中提供。Chrome 和 Android 开发者均可以使用此服务。如需了解状态更新，请参阅这篇公告博文。参阅 API 说明文档和信任模型说明文档，详细了解 Protected Audience 键值对服务。

对于初始测试，使用“自带服务器”模型。从长远来看，广告技术平台需要使用在可信执行环境中运行的开源 Protected Audience 键值对服务来检索实时数据。

为了确保生态系统有足够的时间进行测试，在第三方 Cookie 被弃用之前，我们预计不会要求使用开源键值对服务或 TEE。在此次过渡之前，我们将通知开发者开始测试和采用。

检测功能支持

在使用 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？

您可以以网站所有者或个人用户身份阻止对 Protected Audience API 的访问。

网站如何控制访问权限？

Protected Audience 最终将要求网站设置权限政策以允许使用 Protected Audience 功能。这将有助于确保任意第三方在没有网站的知识。不过，为了便于您在首次源试用期间进行测试，默认情况下，此要求会被豁免。希望在测试期间明确停用 Protected Audience 功能的网站可以使用相关权限政策来禁止访问。

有两项 Protected Audience 权限政策可以单独设置：

“join-ad-interest-group”用于启用/停用将浏览器添加到兴趣群体的功能
run-ad-auction：可启用/停用设备端竞价的运行功能

通过指定以下设置，可在第一方环境中完全停用对 Protected Audience API 的访问权限 HTTP 响应标头中的权限政策：

Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()

您可以禁止在 iframe 中使用 API，方法是将以下 allow 属性添加到 iframe 元素：

<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>

提议的首个 Protected Audience 源试用权限政策部分提供了更多详细信息。

用户选择停用

用户可以使用以下任一项来阻止访问 Protected Audience API 和其他 Privacy Sandbox 功能以下机制：

在 Chrome 设置中停用 Privacy Sandbox 试用：设置 > 安全和隐私权 >Privacy Sandbox。也可通过 chrome://settings/adPrivacy 访问。
在 Chrome 设置中停用第三方 Cookie：设置 >安全和隐私权。
将 Cookie 及其他网站数据设为“阻止第三方 Cookie”或“阻止所有 Cookie” chrome://settings/cookies起。
使用无痕模式。

Protected Audience 说明文档详细介绍了 API 设计元素，并介绍了该 API 如何努力实现隐私保护目标。

调试 Protected Audience Worklet

从 Chrome Canary 98.0.4718.0 开始，您可以在 Chrome 开发者工具中调试 Protected Audience Worklet。

第一步是通过 Event Listener Breakpoints 窗格中的新类别设置断点在来源面板中查看相关信息。

以下内容的屏幕截图：
Chrome Canary 版中的开发者工具，其中突出显示了“Sources”面板中的“Event Listener Breakpoints”窗格。
在“广告竞价 Worklet”下，已选择“出价方出价阶段开始”。

当断点触发时，系统会在 Worklet 脚本。您可以使用常规断点或步骤命令来获取出价/评分/报告函数本身。

实时 Worklet 脚本也会显示在“Threads”面板下方。

以下内容的屏幕截图：
Chrome Canary 版中的开发者工具，突出显示“Sources”面板中的“Threads”窗格，显示当前的
已暂停的 Worklet 脚本。

由于某些 Worklet 可能并行运行，因此多个线程可能最终会处于“暂停”状态状态您可以使用线程列表在线程之间切换，以及恢复或检查线程，适当的选择。

观察 Protected Audience 事件

在 Chrome 开发者工具中的“Application”面板中，您可以观察 Protected Audience 兴趣群体和竞价事件。

如果您访问 Protected Audience 演示版购物网站在启用了 Protected Audience 的浏览器中，开发者工具会显示 join 事件的相关信息。

通过
Chrome Canary 版中的开发者工具 Application 面板，其中显示了 Protected Audience 兴趣组的相关信息
加入事件。

如果您现在访问 Protected Audience 演示发布商网站，在启用了 Protected Audience 的浏览器中，开发者工具会显示 bid 和 win 事件的相关信息。

通过
Chrome Canary 版中的开发者工具 Application 面板，显示 Protected Audience 竞价出价和
赢得比赛。

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

在此示例中，用户浏览了一家定制自行车制造商的网站，然后访问了某个新闻网站并看到了自行车制造商出品的一款新自行车的广告

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

假设某位用户访问了一家定制自行车制造商的网站（Google Ads 中的广告客户，），并在一款手工钢制自行车的产品页面上花了些时间。这提供了提供再营销机会的自行车制造商。

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

显示用户在笔记本电脑上的浏览器中查看网站的插图。JavaScript
代码 joinAdInterestGroup() 在浏览器中运行。

解释器部分：浏览器记录兴趣群体

广告客户的需求方平台 (DSP)（或广告客户）本身）调用 navigator.joinAdInterestGroup() 来请求浏览器向浏览器所属的群组的列表。在此示例中，该组名为 custom-bikes，所有者是dsp.example。兴趣群体所有者（在本例中为需求方平台）将买方。兴趣群体成员资格由浏览器存储在用户的设备上，不与浏览器供应商或任何其他人。

注意：joinAdInterestGroup() 的调用上下文的来源必须与兴趣群体一致所有者的来源，因此需要从 iframe 中调用 joinAdInterestGroup()（（例如，来自 DSP），除非兴趣群体所有者的来源与当前文档（例如，网站有自己的兴趣群体）。 runAdAuction 的要求不相同，因此从runAdAuction() <script>代码的性能可能远远超过跨源 iframe。

joinAdInterestGroup() 需要以下权限：

所访问的网站
兴趣群体所有者

例如：必须无法让 malicious.example 调用在未经以下许可的情况下，以dsp.example为所有者joinAdInterestGroup() dsp.example。

来自所访问的网站的权限

同源：默认情况下，系统会为来自以下来源的 joinAdInterestGroup() 调用隐式授予权限与所访问的网站同源，即与当前页面。网站可以使用 Protected Audience 权限政策标头使用 join-ad-interest-group 指令停用 joinAdInterestGroup() 调用。

跨源：从与当前不同的源调用 joinAdInterestGroup() 则只有在所访问的网站设置了允许调用来自跨源 iframe 的 joinAdInterestGroup()。

注意：Protected Audience 当前实现的默认设置为允许调用 joinAdInterestGroup() 网页中的任意位置，甚至是从跨源 iframe 中加载。以后，如果网站所有者调整其权限政策，计划会默认禁止跨源 iframe，如 Protected Audience 说明文档中所述。

兴趣群体所有者的权限

通过调用 joinAdInterestGroup() 隐式授予了兴趣群组所有者权限来自与兴趣组所有者同源的 iframe。例如，dsp.example iframe 可以针对 dsp.example 拥有的兴趣群体调用 joinAdInterestGroup()。

我们的方案是：joinAdInterestGroup() 可以在所有者网域中的网页或 iframe 中运行，或者委托给使用 .well-known 网址中列表提供的其他网域。

使用 navigator.joinAdInterestGroup()

以下是可以如何使用该 API 的示例：

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  dailyUpdateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

传递给函数的 interestGroup 对象的大小不得超过 50 kiB，否则调用将失败。第二个参数用于指定兴趣群体的持续时间，上限为 30 天。连续调用会覆盖之前存储的值。

要点：用作 Protected Audience API 方法参数的所有网址都必须来自安全来源：所有资源都必须通过 HTTPS 网址提供。如何使用 HTTPS 进行本地开发介绍了在本地运行 Protected Audience 时如何执行此操作。此外，biddingLogicUrl、decisionLogicUrl 和 trustedBiddingSignals 都需要 X-Allow-FLEDGE: true HTTP 响应标头。

兴趣组属性

属性	必填	示例	角色
`owner`	必填	`'https://dsp.example'`	兴趣群体所有者的来源。
`name`	必填	`'custom-bikes'`	兴趣群体的名称。
`biddingLogicUrl`**	选填*	`'https://dsp.example/bid/custom-bikes/bid.js'`	在 Worklet 中运行的出价 JavaScript 的网址。
`biddingWasmHelperUrl`**	选填*	`'https://dsp.example/bid/custom-bikes/bid.wasm'`	由 `biddingLogicUrl` 驱动的 WebAssembly 代码的网址。
`dailyUpdateUrl`**	可选	`'https://dsp.example/bid/custom-bikes/update'`	返回 JSON 以更新兴趣群体属性的网址。（请参阅更新兴趣群体。）
`trustedBiddingSignalsUrl`**	可选	`'https://dsp.example/trusted/bidding-signals'`	向出价方的可信服务器发出的键值对请求的基准网址。
`trustedBiddingSignalsKeys`	可选	`['key1', 'key2' ...]`	用于向键值对可信服务器发送请求的键。
`userBiddingSignals`	可选	`{...}`	所有者在出价期间可以使用的其他元数据。
`ads`	选填*	`[bikeAd1, bikeAd2, bikeAd3]`	可能会针对该兴趣群体呈现的广告。
`adComponents`	可选	`[customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]`	由多个部分组成的广告的组件。

* 除了 owner 和 name 之外，所有属性都是可选的。biddingLogicUrl和ads 属性是可选属性，但若要参与竞价，此属性为必需属性。一些用例创建不含这些属性的兴趣组：例如，兴趣组所有者可能希望将浏览器添加到兴趣群体中，投放尚未投放的广告系列，或可能暂时用尽了广告预算。

** biddingLogicUrl、biddingWasmHelperUrl、dailyUpdateUrl 和 trustedBiddingSignalsUrl 网址必须与所有者同源。ads 和 adComponents 网址没有此类限制。

更新兴趣群体属性

dailyUpdateUrl 用于指定一个 Web 服务器，该服务器会返回定义兴趣群体属性的 JSON。（对应于传递给 navigator.joinAdInterestGroup() 的兴趣群体对象）。这个为群组所有者提供了一种机制，用于定期更新。在当前实现中，以下属性可以更改：

biddingLogicUrl
biddingWasmHelperUrl
trustedBiddingSignalsUrl
trustedBiddingSignalsKeys
ads
priority

系统不会覆盖 JSON 中未指定的任何字段，只有 JSON 中指定的字段才会获得已更新，而调用 navigator.joinAdInterestGroup() 会覆盖任何现有的兴趣群体。

系统会尽最大努力进行更新，在以下情况下，更新可能会失败：

网络请求超时（目前为 30 秒）。
其他网络故障。
JSON 解析失败。

如果连续更新时间过长，也可以取消更新。不会对已取消的（剩余）更新施加任何速率限制。更新仅限于最多每天一次。因网络错误而失败的更新会在一小时后重试，并且因与互联网断开连接而失败的更新会在重新连接后立即重试。

手动更新

可通过以下代码，手动触发对当前框架来源所拥有的兴趣群体的更新： navigator.updateAdInterestGroups()。速率限制可防止过于频繁的更新：在达到速率限制之前，重复调用 navigator.updateAdInterestGroups() 不会执行任何操作期限（目前为一天）。如果出现以下情况，系统会重置速率限制针对同一兴趣群体 owner 和 name 再次调用 navigator.joinAdInterestGroup()。

自动更新

为竞价加载的所有兴趣群体在竞价完成后都会自动更新，则需遵循与手动更新相同的速率限制对于至少包含一个兴趣群体的每位所有者就好像是 navigator.updateAdInterestGroups() 是从来源与所有者匹配的 iframe。

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

ads 和 adComponents 对象包括广告素材网址，并且可以选择性地可在出价时使用的元数据例如：

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

买方如何出价？

兴趣群体所有者提供的位于 biddingLogicUrl 的脚本必须包含一个generateBid() 函数。当广告空间卖方调用 navigator.runAdAuction() 时，generatedBid() 对于浏览器所属的每个兴趣组，如果相应的兴趣其所有者受邀出价。换句话说，系统会针对每个候选定位设置调用一次 generateBid() 。卖方为传递的竞价配置参数提供 decisionLogicUrl 属性至 navigator.runAdAuction()。此网址中的代码必须包含一个 scoreAd() 函数，该函数为为竞价中的每个出价方运行实验，以便为 generateBid() 返回的各个出价打分。

注意：biddingWasmHelperUrl 属性是可选的，但允许出价方提供 WebAssembly 中需要大量计算开销的子例程，而不是 JavaScript，需要由 biddingLogicUrl 提供的 JavaScript 函数驱动。如果它必须指向使用 application/wasm mimetype 提供的 WebAssembly 二进制文件。通过相应的 WebAssembly.Module 会由浏览器提供给 generateBid() 函数。

广告空间买方提供的位于 biddingLogicUrl 的脚本必须包含 generateBid() 函数。针对每个候选广告调用此函数一次。runAdAuction() 逐一检查每个广告及其相关的出价和元数据，然后将数字受欢迎程度得分。

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  ...
  return {
    ad: adObject,
    bid: bidValue,
    render: renderUrl,
    adComponents: [adComponentRenderUrl1, ...]
   };
}

generateBid() 接受以下参数：

interestGroup
广告买方传递给 joinAdInterestGroup() 的对象。（兴趣群体可通过 dailyUpdateUrl 更新。）
auctionSignals
竞价配置参数的一个属性，传递到 navigator.runAdAuction()。它可提供有关网页上下文（如广告尺寸和发布商 ID）、竞价类型（最高出价或次高价格）以及其他信息元数据。
perBuyerSignals
与 auctionSignals 一样，这是竞价配置的一个属性，参数（由卖方传递给 navigator.runAdAuction()）。这种方法可以提供来自买方服务器关于该网页的信号（如果卖方是 SSP）对买方服务器执行实时出价调用并将响应传回网页直接与买方服务器联系。如果是这样，买方可能希望查看在 generateBid() 中针对这些信号添加签名，以防范篡改。
trustedBiddingSignals
一个对象，其键是trustedBiddingSignalsKeys 兴趣群体，并在 trustedBiddingSignals 请求中返回其值。
browserSignals
由浏览器构建的对象，其中可能包含有关网页的信息上下文（例如当前网页的 hostname，卖家本来可以伪造）和数据（例如该群体在竞价中胜出的时间的记录），设备端频次上限）。

browserSignals 对象具有以下属性：

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  joinCount: 3,
  bidCount: 17,
  prevWins: [[time1,ad1],[time2,ad2],...],
  wasmHelper: ... /* WebAssembly.Module object based on interest group's biddingWasmHelperUrl. */
  dataVersion: 1, /* Data-Version value from the buyer's Key/Value service response(s). */
}

如需计算 bid 值，generateBid() 中的代码可以使用函数的参数。例如：

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
    ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    ...
  }
}

generateBid() 会返回一个包含四个属性的对象：

ad
有关广告的任意元数据，例如卖方希望了解的有关此出价的信息，或广告素材。卖方](/privacy-sandbox/resources/glossary#ssp)会在竞价和决策中使用这些信息广告素材。卖方会在竞价和决策中使用此信息逻辑。
bid
将会参与竞价的数字出价。销售人员必须在一定程度上才能比较因此出价必须使用卖方选择的单位（例如，“USD/ 千”）。如果出价为零或负数，此兴趣群体将不会参与卖方的竞价情况通过这种机制，买方可以针对他们的广告可能会展示，也可能不会展示
render
一个网址或一系列网址，将在此出价在竞价中胜出时用于呈现广告素材。（请参阅广告由多个部分组成。）该值必须与以下任一项的 renderUrl 一致：为兴趣群体定义的广告。
adComponents
一个可选列表，最多包含 20 个由多个部分组成的广告取自兴趣群体参数的 adComponents 属性传递给 navigator.joinAdInterestGroup()。

要求浏览器退出兴趣群体

兴趣群体所有者可以请求从兴趣群体中移除某个浏览器。在其他字词，就会要求浏览器从其所属的兴趣群体列表中移除该兴趣群体。

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

如果用户返回要求浏览器添加兴趣群体的网站，则该兴趣群体的所有者可以调用 navigator.leaveAdInterestGroup() 函数，请求浏览器移除兴趣群体。广告代码也可以针对其兴趣群体调用此函数。

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

后来，该用户访问了一个销售广告空间的网站，在本例中为新闻网站。该网站包含广告资源：使用“广告资源”委托类型实时出价。

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

图示：一个人在笔记本电脑上的浏览器中查看新闻网站。广告
使用 Protected Audience API 进行竞价。

解说部分：卖方开展设备端竞价

广告竞价可能由发布商的 SSP 开展，或者发布商本身竞价的目的是为单个客户选择最合适的广告当前网页上的可用广告位。竞价时会考虑兴趣群体，以及来自键值对服务的广告空间买方和卖方的数据。

广告空间卖方通过调用以下服务向用户浏览器发出请求，以开始广告竞价： navigator.runAdAuction()。

例如：

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

const auctionResultPromise = navigator.runAdAuction(auctionConfig);

runAdAuction() 会返回一个 promise，该 promise 可解析为表示URNurn:uuid:<something> 广告竞价结果。仅当将其传递到围栏框架时，浏览器才能对其进行解码。以供呈现：发布商网页无法检查胜出的广告。

注意：如前所述， joinAdInterestGroup()必须与兴趣群体所有者的一致来源，因此需要从 iframe（例如，joinAdInterestGroup() （来自 DSP）文档（例如，网站有自己的兴趣群体）。 runAdAuction 的要求不相同，因此从runAdAuction() <script>代码的性能可能远远超过跨源 iframe。

decisionLogicUrl 脚本会考虑每个广告及其相关出价和元数据，然后为其指定一个数字适宜性分数。

`auctionConfig` 个房源

属性	必填	示例	角色
`seller`	必填	`'https://ssp.example'`	卖家的来源。
`decisionLogicUrl`	必填	`'https://ssp.example/auction-decision-logic.js'`	竞价 Worklet JavaScript 的网址。
`trustedScoringSignalsUrl`	可选	`'https://ssp.example/scoring-signals'`	卖家可信服务器的网址。
`interestGroupBuyers*`	必填	`['https://dsp.example', 'https://buyer2.example', ...]`	要求参与竞价的所有兴趣群体所有者的来源。
`auctionSignals`	可选	`{...}`	与页面上下文、竞价类型等相关的卖方信息。
`sellerSignals`	可选	`{...}`	根据发布商设置、发出内容相关广告请求等生成的信息。
`sellerTimeout`	可选	`100`	卖方的 `scoreAd()` 脚本的最长运行时间（毫秒）。
`perBuyerSignals`	可选	`{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ...}`	来自每个特定买方的服务器中有关该网页的情境信号。
`perBuyerTimeouts`	可选	`50`	特定买方的 `generateBid()` 脚本的最长运行时间（毫秒）。
`componentAuctions`	可选	`[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]`	组件竞价的其他配置。

* 卖方可指定 interestGroupBuyers: '*'，以允许所有兴趣群体出价。随后，系统会根据除了包含兴趣群体所有者在内的其他条件来接受或拒绝广告。例如，卖方可能会审核广告素材，以确认其符合其政策。

** Protected Audience 的当前实现方案不支持 additionalBids。阅读竞价参评者部分 Protected Audience 铺垫消息。

如何选择广告？

decisionLogicUrl 中的代码（传递给 runAdAuction()）必须包含 scoreAd() 函数。该测试针对每个广告运行一次以确定其受欢迎程度

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

scoreAd() 接受以下参数：

adMetadata
买方提供的任意元数据。
bid
出价数值。
auctionConfig
传递给 navigator.runAdAuction() 的竞价配置对象。
trustedScoringSignals
在竞价时从卖方可信服务器检索的值，来代表卖方对广告的看法
browserSignals
由浏览器构造的对象，其中包含浏览器以及卖方的竞价脚本想要验证哪一项：

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* Data-Version value from the seller's Key/Value service response. */
}

在竞价开始之前，卖方会找到最适合可用广告位的内容相关广告。属于其 scoreAd() 逻辑会拒绝所有比内容相关广告胜出者更高的广告。

5. 卖方和参与的买方从键值对服务接收实时数据

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

说明部分：从 Protected Audience 键值对服务提取实时数据。

在广告竞价期间，广告空间卖方可以通过以下方式获取特定广告素材的实时数据：使用 trustedScoringSignalsUrl 属性向键值对服务发出请求，传递给 navigator.runAdAuction() 的竞价配置参数以及键从所有条目的 ads 和 adComponents 字段中所有条目的 renderUrl 属性中获取兴趣群体。

同样，广告空间买方可以使用兴趣组参数的 trustedBiddingSignalsUrl 和 trustedBiddingSignalsKeys 属性传递给 navigator.joinAdInterestGroup()。

调用 runAdAuction() 时，浏览器会向每个广告买方的可信服务器发出请求。通过请求的网址可能如下所示：

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2

基础网址来自 trustedBiddingSignalsUrl。
hostname 由浏览器提供。
keys 值取自 trustedBiddingSignalsKeys。

此请求的响应是一个 JSON 对象，该对象为每个键提供值。

要点：在测试 Protected Audience 的当前初始实验阶段，trustedBiddingSignalsUrl 必须具有与兴趣组所有者同源：请参阅兴趣组属性和自带服务器。

6. 展示胜出的广告

图示：一个人在笔记本电脑上的浏览器中查看新闻网站。广告
，上面有一个锁形图标，表示该广告显示在
围栏框架

说明部分：浏览器呈现胜出的广告

如前所述：runAdAuction() 返回的 promise 将解析为 URN 然后将其传递到围栏框架进行呈现胜出的广告

7. 系统会将竞价结果

说明部分：事件级报告（目前）

注意：长期计划是让浏览器为卖方和买方报告竞价结果使用汇总报告 API 收集报告。作为一种临时的事件级报告机制，实现 reportResult() 卖方和胜出出价方的 reportWin() 可以调用 sendReportTo() 函数。这需要单个参数：表示在竞价完成后提取的网址的字符串，对要报告的事件级信息进行编码。

销售人员报告结果

解释器部分：呈现时的卖方报告

decisionLogicUrl 提供的卖方 JavaScript（也提供了 scoreAd()）添加 reportResult() 函数，以报告竞价结果。

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

传递到此函数的参数是：

auctionConfig
传递给 navigator.runAdAuction() 的竞价配置对象。

browserSignals（
）由浏览器构建的对象，用于提供竞价的相关信息。例如：

{
  'topWindowHostname': 'publisher.example',
  'interestGroupOwner': 'https://dsp.example',
  'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
  'bid:' <bidValue>,
  'desirability': <winningAdScore>
}

此函数的返回值将用作胜出出价方的 sellerSignals 参数 reportWin() 函数。

获胜出价方报告结果

说明部分：买方报告呈现和广告事件

胜出出价方的 JavaScript（也提供了 generateBid()）可能包含 reportWin() 函数，用于报告竞价结果。

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

注意：如果未定义 reportWin()，Chrome 中当前实现的 Protected Audience 将会发出警告。

传递到此函数的参数是：

auctionSignals和perBuyerSignals
向胜出出价方的 generateBid() 传递的同样值相同。
sellerSignals
reportResult() 的返回值，为卖方提供以便有机会向买方传递信息

browserSignals
由浏览器构建的对象，用于提供竞价的相关信息。例如：

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid:' <bidValue>
}

实施暂时性损失/胜出报告

Chrome 中暂时提供了以下两种用于生成竞价报告的方法：

forDebuggingOnly.reportAdAuctionLoss()
forDebuggingOnly.reportAdAuctionWin()

这些方法都接受一个参数：在竞价完成后获取的网址。他们可以使用不同的网址参数在 scoreAd() 和 generateBid() 中多次调用。

只有在竞价完成时，Chrome 才会发送失败/胜出的调试报告。如果竞价是取消（例如，由于新的导航），则系统不会生成任何报告。

Chrome 中默认提供这些方法。为了能够测试这些方法，请在 chrome://settings/adPrivacy 下启用所有广告隐私权 API。如果您在运行 Chrome 时带有命令行标记以启用 Protected Audience，则需要执行以下操作：通过添加 BiddingAndScoringDebugReportingAPI 标志来显式启用这些方法。如果标志，则这些方法仍然可用，但不执行任何操作。

8. 报告一次广告点击

插图：
一个人在新闻网站上点击自行车广告，位于围栏框架中，并有报告
并将数据提供给卖方和买方

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

下图概述了 Protected Audience 广告竞价的每个阶段：

Protected Audience 与 TURTLEDOVE 之间有何区别？

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

Protected Audience 遵循 TURTLEDOVE 的总体原则。有些在线广告是基于向可能感兴趣的用户展示广告，而这些用户之前与广告客户或广告联盟有过互动。一直以来，广告客户都是利用该功能来识别用户浏览网站时的真实身份，这是当今网络的核心隐私问题。

TURTLEDOVE 项目旨在提供一个新的 API 来解决此用例，同时提供一些重要的隐私保护改进：

浏览器（而不是广告客户）保存着有关广告客户对人感兴趣的内容。
广告客户可以根据兴趣投放广告，但不能将该兴趣与其他用户兴趣结合起来用户的相关信息，特别是他们是谁或正在访问什么网页。

Protected Audience 源自 TURTLEDOVE 及一系列相关修改提案，旨在为使用该 API 的开发者提供更好的服务：

在 SPARROW 中： Criteo 提议增加一个在可信执行环境 (TEE) 中运行的（“Gatekeeper”）服务模型。Protected Audience 可以更有限地使用 TEE，以便进行实时数据查找和汇总报告。
NextRoll 的 TERN 和 Magnite 的鹦鹉提案说明了买方和卖方在设备端竞价中扮演的不同角色。 Protected Audience 的广告出价/评分流程正是基于这项成果而构建。
RTB House 的基于结果的策略和商品级 TURTLEDOVE 改进的匿名模型和设备端竞价的个性化功能
PARAKEET 是 Microsoft 提出的类似 TURTLEDOVE 的广告服务，该服务依赖于在 TEE 中运行的代理服务器以匿名方式处理广告请求并强制保护用户隐私，属性。Protected Audience 未采用此代理模型。我们将 JavaScript API 以匹配 PARAKEET 和 Protected Audience，以支持未来进一步整合最佳两个提案的功能

Protected Audience 尚未阻止网站的广告网络学习用户会看到哪些广告。预计可以对 API 进行修改，使其具有更高的私密性。

可用的浏览器配置是什么？

用户可以启用或停用 Chrome 中 Privacy Sandbox 试用计划， chrome://settings/adPrivacy 中的顶层设置。在初始测试期间，能够使用这项高级 Privacy Sandbox 设置选择停用 Protected Audience。Chrome 计划允许用户可查看和管理整个网络中已将他们添加到的兴趣群体列表。与 Privacy Sandbox 技术本身一样，用户设置随着用户、监管机构和其他人的反馈不断改进。

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

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

互动和分享反馈

GitHub：阅读提案提出问题并关注讨论。
W3C：讨论“改进网络广告业务”行业用例群组。
开发者支持：提出问题并加入 Privacy Sandbox 开发者支持代码库。
FLEDGE 邮寄名单：fledge-api-announce 提供有关该 API 的公告和更新。
加入 Protected Audience 预定的通话（从每个第二周）。我们欢迎每个人加入——要参与，首先请务必加入 WICG。你可以积极参与，也可以只听音乐！
使用 Privacy Sandbox 反馈表单，以便在公共论坛之外与 Chrome 团队私下分享反馈。

获取支持

要咨询与您的实现、演示或相关文档相关的问题，请按以下步骤操作：

提出新问题（位于 privacy-sandbox-dev-support 代码库中）。请务必为 Protected Audience 选择问题模板。
在 GitHub 上的演示代码库中提出问题。
如需了解有关如何使用 API 满足您的用例的一般性问题，在提案库中提交问题。

如果在 Chrome 中实现 Protected Audience API 时出现的错误和问题： * 查看现有问题针对该 API 报告的数据。 * 在 crbug.com/new 上提出新问题。

获取更新

要获取有关 API 的状态变化的通知，请加入开发者。
要密切关注目前在 API 上进行的所有讨论，请在 GitHub。这要求您拥有或创建一个 GitHub 账号。
如需了解 Privacy Sandbox 的总体动态，请订阅 RSS Feed [Progress in the Privacy 沙盒]。

了解详情

Protected Audience API：技术性概览。
Protected Audience 演示：基本的 Protected Audience 部署演示。
“Protected Audience 演示”视频：介绍了演示代码，并展示了如何使用 Chrome 开发者工具进行 Protected Audience 调试。
Protected Audience API 技术说明
深入了解 Privacy Sandbox
设计原型

照片由 Ray Hennessy 拍摄，由 Unspin 提供。