定义受众群体数据

了解如何使用 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 天。连续调用会覆盖之前存储的值。

要点：用作 Protected Audience API 方法参数的所有网址都必须来自安全的源：所有资源都必须通过 HTTPS 网址提供。如何使用 HTTPS 进行本地开发一文介绍了如何在本地运行 Protected Audience API 时执行此操作。 此外，biddingLogicUrl、decisionLogicUrl 和 trustedBiddingSignals 还需要 X-Allow-FLEDGE: true HTTP 响应标头。

必要属性

兴趣群体的唯一必需属性只有 owner 和 name：

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

可选属性

其余属性是可选的：

biddingLogicUrl^1、2

示例：https://dsp.example/bid/custom-bikes/bid.js

角色：用于在 Worklet 中出价的 JavaScript 的网址。

biddingWasmHelperUrl^1、2

示例：https://dsp.example/bid/custom-bikes/bid.wasm

角色：由 biddingLogicUrl 驱动的 WebAssembly 代码的网址。

updateUrl²

示例：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]

角色：由多个部分组成的广告的组件。

¹ biddingLogicUrl 和 ads 属性是可选的，但必须设置才能参与竞价。在某些情况下，用户可能需要创建不含这些属性的兴趣群体：例如，某个兴趣群体所有者可能希望将浏览器添加到兴趣群体中，以投放尚未投放的广告系列，或将其用于其他的未来用途；或者，兴趣群体的广告预算可能暂时已用尽。

² 在 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-匿名性时使用后备广告。有一定程度的后备广告本身不具备 k-匿名性，因此您可以考虑从一开始就只对后备广告出价。或许这样做的概率为 1%，例如，如果这个水平比较合适，可以确保后备值保持在阈值以上。

最近有一些其他功能的讨论方法，因此，如果您的某些应用场景会导致这种机制出现问题，请继续参与公开讨论，了解如何改进 API。

所有 Protected Audience API 参考文档

以下是 API 参考指南：

• Protected Audience API 开发者指南。
• 有关 Protected Audience 兴趣群体和出价生成的广告买方指南。
• Protected Audience 广告竞价广告卖方指南。
• 关于报告竞价结果的指南
• Protected Audience 广告竞价延迟时间方面的最佳实践
• 对 Protected Audience 进行问题排查

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