定义受众群体数据

了解如何使用 Protected Audience API 创建兴趣群体,进而定义受众群体。阅读开发者指南,了解 Protected Audience API 的完整生命周期;并参阅 Protected Audience API 说明文档,了解浏览器如何记录兴趣群体的深入建议。

不是开发者?参阅 Protected Audience API 概览

Protected Audience API 兴趣群体代表一组具有共同兴趣的用户,与一个再营销名单相对应。每个 Protected Audience API 兴趣群体都有一个所有者

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

广告客户的需求方平台 (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 天。连续调用会覆盖之前存储的值。

必要属性

兴趣群体仅有的必需属性 ownername

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

可选属性

其余属性是可选的:

biddingLogicUrl12
示例:https://dsp.example/bid/custom-bikes/bid.js
角色:在 Worklet 中运行的出价 JavaScript 的网址。
biddingWasmHelperUrl12
示例: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 biddingLogicUrlads 属性是可选的,但若要参与竞价,则必须提供。在某些情况下,创建兴趣群体时可能缺少这些属性:例如,兴趣群体所有者可能希望将浏览器添加到兴趣群体中,以便投放尚未投放的广告系列,或将浏览器添加到兴趣群体以留待将来用于其他用途,或者他们可能暂时用尽了广告预算。

2 在 Protected Audience API 的当前实现中,biddingLogicUrlbiddingWasmHelperUrlupdateUrltrustedBiddingSignalsUrl 必须与所有者具有相同的来源。这可能不是长期限制,adsadComponents 网址没有此类限制。

针对某一兴趣群体指定广告

adsadComponents 对象包括广告素材的网址以及可在出价时使用的任意元数据(可选)。

例如:

{
  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 说明信息还详细介绍了功能支持和限制条件。