此页面由 Cloud Translation API 翻译。

FLEDGE API 开发者指南
bookmark_border 使用集合让一切井井有条根据您的偏好保存内容并对其进行分类。

本文的适用对象

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

Protected Audience API 对该提案进行了较少技术性的概述，并提供了术语表。
Protected Audience 演示提供了基本 FLEDGE 部署的演示。
Protected Audience 演示视频介绍了演示代码的运作方式，并展示了如何使用 Chrome 开发者工具进行 Protected Audience 调试。

什么是 Protected Audience？

Protected Audience API 是一项针对再营销和自定义受众群体的相关使用情形而制定的 Privacy Sandbox 提案，旨在让第三方无法使用该 API 跟踪用户的跨网站浏览行为。该 API 支持浏览器在设备端开展竞价，以便为用户之前访问过的网站选择相关广告。

Protected Audience 是 TURTLEDOVE 系列提案中第一个在 Chromium 中实现的实验。

下图概述了 FLEDGE 生命周期：

一张插图，概述了 FLEDGE 生命周期的每个阶段 — FLEDGE 生命周期。

如何试用 Protected Audience？

Protected Audience 演示版

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

演示视频介绍了演示代码的运作方式，并展示了如何使用 Chrome 开发者工具进行 Protected Audience 调试。

参与 Protected Audience 源试用

桌面版 Chrome Beta 101.0.4951.26 及更高版本中推出了 Privacy Sandbox 相关性和效果衡量源试用，适用于 Protected Audience、Topics 和 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 的浏览器时设置 flag。如需查看 Protected Audience 标志的完整列表，请使用 Chromium 代码搜索。

最新版 Chrome 支持哪些功能？

我们将在 Chromium 中通过功能标志提供 Protected Audience，作为一项初步实验来测试 Protected Audience 提案的以下功能：

兴趣群体：由浏览器存储，包含用于配置广告出价和呈现的相关元数据。
买方（DSP 或广告客户）在设备端出价：基于存储的兴趣群组和来自卖方的信号。
卖方（SSP 或发布商）进行的设备端广告选择：根据竞价出价和买方的元数据。
在暂时放宽的围栏帧版本中呈现广告：允许广告呈现网络访问和日志记录。

API 说明文档详细介绍了功能支持和限制。

兴趣群体权限

Protected Audience 当前实现的默认设置是允许从网页中的任何位置（甚至跨网域 iframe）调用 joinAdInterestGroup()。未来，在网站所有者有时间调整其跨网域 iframe 权限政策后，我们计划禁止从跨网域 iframe 进行调用，如说明文档中所述。

键值对服务

在 Protected Audience 广告竞价期间，浏览器可以访问键值对服务，该服务会返回简单的键值对，以向广告买方提供信息，例如剩余的广告系列预算。Protected Audience 提案强制要求此服务器“不会执行事件级日志记录，也不会根据这些请求产生其他副作用”。

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

在初始测试中，使用“自带服务器”模型。从长远来看，广告技术平台需要使用在可信执行环境中运行的开源 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 功能。这有助于确保未经网站知情，任意第三方都无法使用该 API。不过，为方便您在首次来源试用期间进行测试，系统会默认豁免此要求。如果网站希望在测试期间明确停用 Protected Audience 功能，可以使用相关的权限政策来阻止访问。

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

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

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

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

您可以通过向 iframe 元素添加以下 allow 属性，在 iframe 中停用 API 的使用：

<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：依次选择设置 > 安全和隐私。
在 chrome://settings/cookies 中，将Cookie 及其他网站数据设为“阻止第三方 Cookie”或“阻止所有 Cookie”。
使用无痕模式。

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

调试 Protected Audience worklet

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

第一步是在 Sources 面板的 Event Listener Breakpoints 窗格中通过新类别设置断点。

Chrome Canary 中 Chrome 开发者工具的屏幕截图，突出显示了“Sources”（来源）面板中的“Event Listener Breakpoints”（事件监听器断点）窗格。
在“广告竞价 Worklet”下方选择“出价方出价阶段开始”。

当断点触发时，执行会在 worklet 脚本顶级第一个语句之前暂停。您可以使用常规断点或步骤命令进入出价/评分/报告函数本身。

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

Chrome Canary 中 DevTools 的屏幕截图，突出显示了“Sources”（来源）面板中的“Threads”（线程）窗格，其中显示了当前已暂停的工作流脚本。

由于某些 worklet 可能会并行运行，因此多个线程可能会最终处于“暂停”状态；您可以使用线程列表在线程之间切换，并根据需要恢复或更仔细地检查它们。

观察 Protected Audience 事件

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

如果您在启用了 Protected Audience 的浏览器中访问 Protected Audience 演示版购物网站，则 DevTools 会显示有关 join 事件的信息。

Chrome Canary 中的“开发者工具”应用面板，显示了 Protected Audience 兴趣群体加入事件的相关信息。

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

Chrome Canary 中的“开发者工具”应用面板，显示有关 Protected Audience 竞价出价和胜出事件的信息。

Protected Audience API 如何运作？

在此示例中，用户浏览了某个定制自行车制造商的网站，之后访问了某个新闻网站，然后看到了该自行车制造商的新自行车的广告。

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

假设用户访问了定制自行车制造商（在本例中为广告客户）的网站，并在手工钢架自行车的商品页面上花费了一些时间。这为自行车制造商提供了再营销机会。

2. 系统会要求用户的浏览器添加兴趣群体

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

说明部分：浏览器会记录兴趣组

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

注意：joinAdInterestGroup() 调用上下文的来源必须与兴趣群组所有者的来源匹配，因此除非兴趣群组所有者的来源与当前文档的来源匹配（例如，具有自己的兴趣群组的网站），否则需要从 iframe（例如 DSP）调用 joinAdInterestGroup()。 runAdAuction 没有相同的要求，因此从 <script> 标记调用 runAdAuction() 的性能可能远远优于跨源 iframe。

joinAdInterestGroup() 需要获得以下用户的权限：

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

例如：malicious.example 不得在未经 dsp.example 授权的情况下，以 dsp.example 为所有者调用 joinAdInterestGroup()。

所访问网站的权限

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

跨源：只有当所访问的网站设置了允许从跨源 iframe 调用 joinAdInterestGroup() 的权限政策时，才能从与当前网页不同的来源调用 joinAdInterestGroup()。

注意：Protected Audience 当前实现的默认设置是允许从网页中的任何位置（包括跨源 iframe）调用 joinAdInterestGroup()。未来，在网站所有者有时间调整其权限政策后，该方案将默认禁止来自跨源 iframe 的调用，如 Protected Audience 说明中所述。

获得兴趣群组所有者的许可

通过从与兴趣群组所有者相同的来源的 iframe 调用 joinAdInterestGroup()，系统会隐式授予兴趣群组所有者权限。例如，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()，则速率限制会重置。

自动更新

竞价完成后，为竞价加载的所有兴趣群体都会自动更新，更新频率限制与手动更新相同。对于至少有一个兴趣群体参与竞价的每个所有者，系统都会像从来源与该所有者匹配的 iframe 调用 navigator.updateAdInterestGroups() 一样。

为兴趣群体指定广告

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

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

买方如何出价？

兴趣群组所有者提供的 biddingLogicUrl 脚本必须包含 generateBid() 函数。当广告空间卖方调用 navigator.runAdAuction() 时，如果兴趣群体的所有者受邀出价，系统会针对浏览器所属的每个兴趣群体调用一次 generatedBid() 函数。也就是说，系统会为每个候选广告调用一次 generateBid()。卖方在传递给 navigator.runAdAuction() 的竞价配置参数上提供 decisionLogicUrl 属性。此网址中的代码必须包含 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
与广告相关的任意元数据，例如卖方希望了解的此出价或广告素材的信息。卖方](/resources/glossary#ssp) 会在竞价和决策广告素材中使用这些信息。卖方会在其竞价和决策逻辑中使用这些信息。
bid
将进入竞价的数字出价。卖方必须能够比较来自不同买方的出价，因此出价必须采用卖方选择的单位（例如“每千次展示费用”）。如果出价为零或负数，则此兴趣群体将完全不会参与卖方的竞价。借助此机制，买方可以针对其广告的可能或不可能展示位置实现任何广告客户规则。
render
如果此出价在竞价中胜出，系统将使用此网址或网址列表来呈现广告素材。（请参阅 API 说明中的由多个部分组成的广告。）该值必须与为兴趣群体定义的广告之一的 renderUrl 匹配。
adComponents
一个可选列表，用于包含多部分的广告，最多包含 20 个组件，取自传递给 navigator.joinAdInterestGroup() 的兴趣群体参数的 adComponents 属性。

要求浏览器退出兴趣群组

兴趣群组所有者可以请求将浏览器从兴趣群组中移除。换句话说，系统会要求浏览器从其所属的兴趣群组列表中移除相应兴趣群组。

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 会解析为表示广告竞价结果的 URN (urn:uuid:<something>)。只有在传递到围栏帧进行呈现时，浏览器才能对其进行解码：发布商页面无法检查胜出的广告。

注意：如前所述，joinAdInterestGroup() 调用上下文的来源必须与兴趣群组所有者的来源匹配，因此除非兴趣群组所有者的来源与当前文档的来源匹配（例如，具有自己的兴趣群组的网站），否则需要从 iframe（例如 DSP）调用 joinAdInterestGroup()。 runAdAuction 没有相同的要求，因此从 <script> 标记调用 runAdAuction() 的性能可能远远优于跨源 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 键值对服务中提取实时数据。

在广告竞价期间，广告资源卖方可以使用传递给 navigator.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 的当前初始实验阶段，trustedBiddingSignalsUrl 的来源必须与兴趣群体所有者相同：请参阅兴趣群体媒体资源和自行提供服务器。

6. 系统会展示胜出的广告

插图：显示一个人在笔记本电脑的浏览器中查看新闻网站。显示一则自行车广告（八折优惠），上面有一个锁形图标，表示广告在有围栏的框架中展示。

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

如前所述：runAdAuction() 返回的 Promise 会解析为 URN，该 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>
}

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

胜出的出价方报告结果

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

胜出出价方的 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 是 TURTLEDOVE 系列提案中在 Chromium 中实现的第一个实验。

Protected Audience 遵循 TURTLEDOVE 的概要原则。一些在线广告会根据用户之前与广告客户或广告网络互动的情况，向可能感兴趣的用户展示广告。传统上，这种方法的运作方式是，广告客户在用户浏览网站时识别特定用户，这也是当今网络世界中的一个核心隐私问题。

TURTLEDOVE 计划旨在提供一个新 API 来实现此用例，同时提供一些关键的隐私保护功能：

浏览器（而非广告客户）会存储广告客户认为用户感兴趣的信息。
广告客户可以根据兴趣投放广告，但不能将该兴趣与用户的其他信息（尤其是用户是谁或他们正在访问哪个网页）相结合。

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

在 SPARROW 中：Criteo 提议添加在可信执行环境 (TEE) 中运行的服务模型（“Gatekeeper”）。Protected Audience 对 TEE 的使用更为有限，仅用于实时数据查询和汇总报告。
NextRoll 的 TERN 和 Magnite 的 PARRROT 提案介绍了买方和卖方在设备端竞价中的不同角色。Protected Audience 的广告出价/评分流程基于这项工作。
RTB 广告交易平台的基于结果和产品级 TURTLEDOVE 修改改进了设备端竞价的匿名性模型和个性化功能
PARAKEET 是 Microsoft 提出的一种类似 TURTLEDOVE 的广告服务，它依赖于在浏览器和广告技术提供商之间运行在 TEE 中的代理服务器，以对广告请求进行匿名化处理并强制执行隐私保护属性。Protected Audience 尚未采用此代理模型。我们正在使 PARAKEET 和 Protected Audience 的 JavaScript API 保持一致，以便在未来进一步整合这两项提案的最佳功能。

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

有哪些浏览器配置可用？

用户可以通过在 chrome://settings/adPrivacy 中启用或停用顶级设置，调整自己在 Chrome 中参与 Privacy Sandbox 试用的状态。在初始测试期间，用户将能够使用此高级 Privacy Sandbox 设置来停用 Protected Audience。Chrome 计划允许用户查看和管理将他们纳入其中的兴趣群体名单（这些兴趣群体是根据他们访问过的网站而生成的）。与 Privacy Sandbox 技术本身一样，用户设置可能会随着用户、监管机构和其他人的反馈而不断演变。

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

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

互动和分享反馈

GitHub：阅读提案，提出问题和关注讨论。
W3C：在 Improving Web Advertising Business Group 中讨论行业用例。
开发者支持：在 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 时出现的 bug 和问题，请执行以下操作： * 查看针对该 API 报告的现有问题。 * 前往 crbug.com/new 提出新问题。

获取更新

如需接收 API 状态变更通知，请加入面向开发者的邮寄名单。
如需密切关注有关该 API 的所有最新讨论，请点击 GitHub 上的提案页面上的关注按钮。这需要您拥有或创建 GitHub 账号。
如需获取有关 Privacy Sandbox 的整体动态，请订阅 RSS Feed [Privacy Sandbox 进度]。

了解详情

Protected Audience API：对该提案的非技术概述。
Protected Audience 演示版：演示了基本 Protected Audience 部署。
Protected Audience 演示视频：介绍了演示代码，并展示了如何使用 Chrome 开发者工具进行 Protected Audience 调试。
Protected Audience API 技术说明
深入了解 Privacy Sandbox
意图到原型

照片由 Ray Hennessy 拍摄，选自 Unsplash 网站。