此页面由 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 是要在 Chromium 中的 TURTLEDOVE 提案系列中实现的第一个实验。

下图简要介绍了 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、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 源试用详细信息中提供了有关首次试用目标的更多详细信息，并说明了支持的功能。

使用 `chrome://flags` 或功能标志进行测试

您可以在桌面版 Chrome Beta 版 101.0.4951.26 及更高版本中为单个用户测试 Protected Audience： * 通过启用 chrome://flags/#privacy-sandbox-ads-apis。 * 通过从命令行设置标志。

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

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

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

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

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

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

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

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

最新版 Chrome 支持哪些功能？

Protected Audience 将作为首个实验测试在 Chromium 中的功能标志之后，以测试 Protected Audience 提案的以下功能：

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

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

兴趣群体权限

Protected Audience 的当前实现方案默认允许从网页中的任何位置调用 joinAdInterestGroup()，即使从跨网域 iframe 中调用也是如此。将来，一旦网站所有者有时间调整其跨网域 iframe 权限政策，我们计划禁止来自跨网域 iframe 的调用，如解释中所述。

键值对服务

在 Protected Audience 广告竞价中，浏览器可以访问键值对服务，该服务会返回简单的键值对，以便向广告买方提供信息（例如剩余的广告系列预算）。Protected Audience 提案要求该服务器“不执行事件级日志记录，并且没有基于这些请求的其他副作用”。

Privacy Sandbox GitHub 代码库中现在提供了 Protected Audience 键值对服务代码。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 中使用 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：依次点击设置 > 安全和隐私。
在 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 中开发者工具的屏幕截图，突出显示了“Sources”面板中的“Event Listener Breakpoints”窗格。
已在“广告竞价 Worklet”下选择“出价方出价阶段开始”。

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

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

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

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

观察 Protected Audience 事件

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

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

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

现在，如果您在启用了 Protected Audience 的浏览器中访问 Protected Audience 演示发布商网站，开发者工具会显示有关 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()”需要获得以下权限： *正在访问的网站 * 兴趣群体所有者

例如：在没有 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 网址提供。如需了解在本地运行 Protected Audience 时如何执行此操作，请参阅如何使用 HTTPS 进行本地开发。此外，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 指定返回定义兴趣群体属性的 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
有关广告的任意元数据，例如卖方希望了解的有关此出价或广告素材的信息。卖方 (/privacy-sandbox/resources/glossary#ssp) 会在其竞价和决策广告素材中使用这些信息。卖方在其竞价和决策逻辑中使用这些信息。
bid
参与竞价的出价金额。卖方必须能够比较不同买方的出价，因此出价必须采用卖方选择的单位（例如“USD”）。如果出价为零或负数，则此兴趣群体根本不会参与卖方的竞价。借助此机制，买方可以实施任何广告客户规则来控制其广告可以展示或不能展示的位置。
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() 会返回一个解析为表示广告竞价结果的 URN (urn:uuid:<something>) 的 promise。只有在传递到围栏框架进行呈现时，浏览器才能对它进行解码：发布商网页无法检查胜出的广告。

注意：如前所述，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，然后传递给围栏框架进行呈现，并且网站展示胜出的广告。

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://flags/#privacy-sandbox-ads-apis，默认情况下，这些方法在 Chrome 中可用。但是，如果您在运行 Chrome 时使用了命令行 flag 以启用 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 中启用或停用顶层设置来调整自己在 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 用户。