定义受众群体数据

了解如何使用 Protected Audience API 创建兴趣群体来定义受众群体。请阅读开发者指南，了解 Protected Audience API 的完整生命周期；另请参阅 Protected Audience API 说明文档，深入了解浏览器如何记录兴趣群体的提案。

不是开发者？请参阅 Protected Audience API 概览。

Protected Audience API 兴趣群体

Protected Audience API 兴趣群体代表具有共同兴趣的一群人，相当于再营销名单。每个 Protected Audience API 兴趣群体都有一个所有者。

兴趣群体所有者在 Protected Audience API 广告竞价中充当买方。兴趣群体成员资格信息由浏览器存储在用户设备上，不会分享给浏览器供应商或任何其他方。

API 功能

joinAdInterestGroup()

广告客户的需求方平台 (DSP) 或广告客户本身会调用 navigator.joinAdInterestGroup()，请求浏览器将某个兴趣群体添加到浏览器的成员资格列表中。

joinAdInterestGroup() 的调用方上下文的来源必须与兴趣群体所有者的来源一致，因此除非兴趣群体所有者的来源与当前文档的来源一致（例如，某个网站拥有自己的兴趣群体），否则需要从 iframe（例如，从 DSP）调用 joinAdInterestGroup()。

joinAdInterestGroup() 需要获得以下方面的许可：

这意味着，在 dsp.example.com 未授予权限的情况下，malicious.example 无法为 dsp.example.com 拥有的兴趣群体调用 joinAdInterestGroup()。

所访问网站的权限

权限可以从同源或跨源授予。默认情况下，系统会授予来自所访问网站的同源（换句话说，来自当前网页的顶级框架的同源）的 joinAdInterestGroup() 调用权限。

用法示例

以下示例展示了如何定义兴趣群体并请求浏览器加入该群体。

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

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

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

必要属性

兴趣组的必需属性只有 owner 和 name：

属性 示例 角色
owner https://dsp.example 兴趣群体所有者的来源。
name custom-bikes 兴趣组的名称。

可选属性

其余属性是可选的：

biddingLogicUrl1、2
示例：https://dsp.example/bid/custom-bikes/bid.js
角色：在工作程序中运行的出价 JavaScript 的网址。
biddingWasmHelperUrl1、2
示例：https://dsp.example/bid/custom-bikes/bid.wasm
角色：由 biddingLogicUrl 驱动的 WebAssembly 代码的网址。
updateUrl2
示例：https://dsp.example/bid/custom-bikes/update
角色：返回 JSON 以更新兴趣组属性的网址。 （请参阅更新受众群体数据和刷新广告。）
trustedBiddingSignalsUrl2
示例：https://dsp.example/trusted/bidding-signals
角色：向出价方的可信键值对服务发出的键值对请求的基本网址。
trustedBiddingSignalsKeys
示例：['key1', 'key2' ...]
角色：用于向键值对可信键值对服务发出请求的密钥。
userBiddingSignals
示例：{...}
角色：所有者可在出价期间使用的其他元数据。
ads1
示例：[bikeAd1, bikeAd2, bikeAd3]
角色：可能会为此兴趣群体呈现的广告。
adComponents
示例：[customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]
角色：由多个部分组成的广告的组件。

1 biddingLogicUrl 和 ads 属性是可选的，但参与竞价时必须提供。在某些使用情形下，可能需要创建不含这些属性的兴趣组：例如，兴趣组所有者可能希望将浏览器添加到尚未投放的广告系列所对应的兴趣组中，以供日后使用，或者他们可能暂时没有广告预算。

2 在 Protected Audience API 的当前实现中，biddingLogicUrl、biddingWasmHelperUrl、updateUrl 和 trustedBiddingSignalsUrl 必须与所有者具有相同的来源。这可能不是长期限制，并且 ads 和 adComponents 网址没有此类限制。

为兴趣群体指定广告

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

例如：

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

leaveAdInterestGroup()

兴趣群体所有者可以请求从兴趣群体中移除浏览器。浏览器会从其成员资格列表中移除该兴趣群体。

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

如果用户返回到曾请求浏览器添加兴趣群体的网站，兴趣群体所有者可以调用 navigator.leaveAdInterestGroup() 函数来请求浏览器移除该兴趣群体。

广告的代码还可以针对其兴趣群体调用此函数。

常见问题解答

对于单个用户，每个群组所有者的兴趣组数量上限是多少？

Chrome 允许每个所有者最多拥有 1,000 个兴趣群体，并允许最多有 1,000 个兴趣群体所有者。这些限制旨在提供安全保障，而不是在常规操作中达到。

如何最大限度地利用符合 k-匿名性阈值的兴趣群体广告？

正如公开说明中所述，由于单个兴趣群体可以包含多个可能展示的广告，因此，只要其最偏好的广告低于阈值，该群体就有机会重新出价以展示其另一个广告作为“后备广告”。这意味着，即使是仍低于 k-匿名性阈值的小型专业广告，也可以选择参与竞价，并且其兴趣群体可以回退到更通用的广告，直到更专业的广告拥有足够大的受众群体。

从策略角度来看，您可以考虑以下事项：

  • 如需开始展示新广告，只需在您希望展示该广告的情况下开始使用该广告出价即可。您无需执行任何其他操作。
  • 您可以设置后备广告，以便在新广告不满足 k-匿名性要求时使用。后备广告本身可能不具有 𝑘-匿名性，因此您可以考虑有时直接使用后备广告进行出价。例如，如果 1% 是一个合适的水平，可确保您预计回退保持在阈值以上，则可以按此比例进行测试。

最近，我们讨论了其他可能的运作方式，因此，如果您有某个用例会因这种机制而出现问题，请继续参与有关如何改进 API 的公开讨论。

所有 Protected Audience API 参考

以下是 API 参考指南：

Protected Audience API 说明信息还详细介绍了功能支持和限制条件。