定义受众群体数据

了解如何使用 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
角色：在 Worklet 中运行的出价 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 允许每个所有者最多 1000 个兴趣群体，最多 1000 个兴趣群体所有者。这些限制旨在作为一种安全措施，在正常使用过程中不会触及。

如何尽可能多地投放满足 k-匿名性阈值的兴趣群体广告？

正如公开解释者所述，由于一个兴趣群体可能会投放多个可能展示的广告，因此该群体将有机会针对另一个广告重新出价，以将其作为“后备广告”任何时候，其首选的选择低于阈值时。这意味着，即使小型专用广告仍低于 k-匿名性阈值，您仍然可以选择参与竞价，其兴趣群体可以回退到较为宽泛的广告，直到更专业的广告拥有足够大的受众群体为止。

从战术的角度来看，您可以考虑以下因素：

  • 要让新广告开始展示，只需根据您希望展示广告的位置开始出价即可。您无需执行任何其他操作。
  • 您可以制作后备广告，以便在新广告不是 k-anon 时使用。您的后备广告本身可能无法使用 k-anon，因此，您有时可以考虑从一开始就只针对后备广告出价。或许您可以在 1% 的时间内执行此操作，例如，如果这个水平能够很好地确保后备广告始终超出阈值，您就可以这样做。

最近有一些讨论过其他工作方式，因此，如果您的某些用例会带来问题，请继续参与有关 API 改进方式的公开讨论。

所有 Protected Audience API 参考文档

以下是 API 参考指南：

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