此页面由 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 提案系列中首次在 Chromium 中实现的实验。

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

如何试用 Protected Audience？

Protected Audience 演示

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

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

参与 Protected Audience 源试用

在桌面设备上，Chrome Beta 101.0.4951.26 及更高版本为 Protected Audience API、Topics 和 Attribution Reporting API 提供了 Privacy Sandbox 相关性和衡量源试用。

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

成功注册试用后，您可以在提供有效试用令牌的网页上试用 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 标志，以启用临时调试损失/胜出报告方法。

使用标志运行 Chromium 一文介绍了如何在从命令行运行 Chrome 和其他基于 Chromium 的浏览器时设置标志。您可以从 Chromium 代码搜索获取 Protected Audience 标志的完整列表。

最新版 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 功能可用。这将有助于确保任意第三方在网站不了解的情况下无法使用该 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=()

您可以通过将以下 allow 属性添加到 iframe 元素中来禁止在 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：设置 > 安全和隐私。
将 Cookie 及其他网站数据设置为 chrome://settings/cookies 中的“阻止第三方 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 版中开发者工具的屏幕截图，其中突出显示了“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. 用户访问广告客户的网站

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

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

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

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

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

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

joinAdInterestGroup() 需要以下权限：

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

例如：未经 dsp.example 许可，malicious.example 不得以 dsp.example 为所有者来调用 joinAdInterestGroup()。

来自所访问的网站的权限

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

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

注意：Protected Audience 的当前实现方案的默认设置是允许从网页中的任何位置调用 joinAdInterestGroup()，即使从跨源 iframe 也是如此。今后，一旦网站所有者有时间调整其权限政策，该方案会默认禁止从跨源 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 二进制文件。浏览器向 generateBid() 函数提供了相应的 WebAssembly.Module。

广告空间买方提供的位于 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
将参与竞价的数字出价。卖方必须能够比较不同买方的出价，因此出价必须采用卖方选择的某个单位（例如“每千次美元”）。如果出价为零或负数，该兴趣群体将完全不参与卖方的竞价。通过这种机制，买方可以实施任何广告主规则来决定其广告可能会展示也可能不展示的位置。
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，此 URI 会传递到围栏框架进行呈现，然后网站会展示胜出的广告。

7. 系统会将竞价结果

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

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

销售人员报告结果

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

decisionLogicUrl（也提供了 scoreAd()）提供的卖方 JavaScript 可包含一个 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 是在 Chromium 的 TURTLEDOVE 提案系列中首次实施的实验。

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

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

浏览器（而非广告客户）保存着有关广告客户认为用户感兴趣的内容的信息。
广告客户可以根据兴趣投放广告，但不能将该兴趣与关于用户的其他信息结合使用，尤其是用户的身份或正在访问的页面。

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

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

Protected Audience 尚未阻止网站的广告网络学习用户会看到哪些广告。我们预计会随着时间的推移修改该 API，使其更加注重隐私保护。

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

用户可以通过在 chrome://settings/adPrivacy 中启用或停用顶层设置来调整参与 Privacy Sandbox 在 Chrome 中的试用活动。在初始测试期间，用户可以使用这项高级别的 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 时出现的 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 拍摄，由 Unspin 提供。