了解报告 ID 在 Protected Audience 竞价中的工作原理
概览
报告 ID 是与广告相关联的标识符，可用于生成出价、对出价进行评分以及生成报告。报告 ID 由买方在兴趣群体配置中提供，在本指南中讨论的各种条件下，这些 ID 都会出现在 generateBid()、scoreAd()、reportResult() 和 reportWin() 中。
通过报告 ID，您可以报告广告的标识符，也可以使用报告 ID 来满足交易等使用情形。
报告 ID 分为以下两种类型：
- 报告 ID 不可选择
buyerReportingId（字符串）buyerAndSellerReportingId（字符串）
- 可选择的报告 ID
selectableBuyerAndSellerReportingIds（字符串数组）
报告 ID 的行为方式因是否使用了可选择的报告 ID 而异。如果仅使用不可选择的报告 ID，则这些 ID 仅在报告函数内可用。如果使用了可选择的报告 ID 以及不可选择的报告 ID（如果需要的话），那么定义的所有 ID 同样可以在 generateBid() 和 scoreAd() 中使用。
报告 ID 不可选择
buyerReportingId 和 buyerAndSellerReportingId 是兴趣群体配置中定义的不可选择的报告 ID，会在买方和卖方报告函数中显示。买方和卖方报告函数只会针对胜出广告运行，并且这些函数将收到为该胜出广告定义的报告 ID。
在没有可选报告 ID 的情况下使用时，买方报告函数会收到 buyerReportingId 或 buyerAndSellerReportingId，具体取决于覆盖行为，卖方报告函数会收到 buyerAndSellerReportingId。如果兴趣组配置中未定义 buyerReportingId 和 buyerAndSellerReportingId，则 reportWin() 函数会接收胜出出价的兴趣组名称 (interestGroupName)。
如果不可选择的 ID 未与可选择的报告 ID 结合使用，则它们在 generateBid() 和 scoreAd() 中不可用。
兴趣群体中的报告 ID
报告 ID 由买方为兴趣组中的每个广告定义：
navigator.joinAdInterestGroup({
owner: 'https://buyer.example',
name: 'example-interest-group',
ads: [{
renderUrl: `https://buyer.example/ad.html`,
// buyerAndSellerReportingId goes to the buyer and seller reporting functions
buyerAndSellerReportingId: 'bsrid123',
// buyerReportingId is defined here as an example, but
// is not used due to the overwrite rules described later
buyerReportingId: 'brid123',
}]
});
卖方报告
在卖方报告阶段，buyerAndSellerReportingId 值可供 reportResult() 使用：
function reportResult(..., browserSignals, ...) {
const {
buyerAndSellerReportingId // 'bsrid123'
} = browserSignals;
sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}
在该 ID 出现在 reportResult() 中之前，系统会检查它是否与兴趣群体所有者、出价脚本网址、呈现网址和广告尺寸（广告尺寸至少在 2025 年第 1 季度之前不会纳入此检查范围）进行 k-匿名性检查。如果它并非 k-匿名化，则 reportResult() 函数仍会运行，但报告 ID 值在函数内不可用。
买家报告
在竞价的买方报告阶段，reportWin() 会获得一个报告 ID。如果兴趣群体中定义了多个报告 ID，则系统会应用一条覆盖规则，其中 buyerAndSellerReportingId 会覆盖 buyerReportingId：
- 如果同时定义了
buyerAndSellerReportingId和buyerReportingId，则buyerAndSellerReportingId会覆盖buyerReportingId，并且buyerAndSellerReportingId将在reportWin()内可用。 - 如果仅定义了
buyerReportingId，则buyerReportingId将可用。 - 如果未定义
buyerAndSellerReportingId或buyerReportingId，则interestGroupName将可用。
function reportWin(..., browserSignals, ...) {
const {
buyerAndSellerReportingId // 'bsrid123'
} = browserSignals;
sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}
系统会检查 reportWin() 中提供的报告 ID 是否具有 k-匿名性，并考虑兴趣群体所有者、出价脚本网址、呈现网址和广告尺寸（至少在 2025 年第 1 季度之前，系统不会将广告尺寸纳入此检查范围）。如果它未通过 k-匿名性检查，则 reportWin() 仍会运行，但报告 ID 值不会在函数内提供。
仅定义了 buyerReportingId
如果兴趣群体配置中仅定义了 buyerReportingId：
navigator.joinAdInterestGroup({
owner: 'https://buyer.example',
name: 'example-interest-group',
ads: [{
renderUrl: `https://buyer.example/ad.html`,
buyerReportingId: 'brid123',
}]
});
然后，buyerReportingId 便可在 reportWin() 中使用：
function reportWin(..., browserSignals, ...) {
const {
buyerReportingId, // 'brid123'
} = browserSignals;
}
在可供 reportWin() 使用之前，系统会检查 buyerReportingId 是否与兴趣群体所有者、出价脚本网址、呈现网址和广告尺寸（广告尺寸至少在 2025 年第 1 季度之前不会纳入此项检查）进行 k-匿名性检查。
仅定义了 buyerAndSellerReportingId
如果兴趣群体配置中仅定义了 buyerAndSellerReportingId：
navigator.joinAdInterestGroup({
owner: 'https://buyer.example',
name: 'example-interest-group',
ads: [{
renderUrl: `https://buyer.example/ad.html`,
buyerAndSellerReportingId: 'bsrid123',
}]
});
然后，reportWin() 中提供了 buyerAndSellerReportingId：
function reportWin(..., browserSignals, ...) {
const {
buyerAndSellerReportingId, // 'bsrid123'
} = browserSignals;
}
在向 reportWin() 提供之前，系统会检查 buyerAndSellerReportingId 是否具有基于兴趣群体所有者、出价脚本网址、呈现网址和广告大小的 k-匿名性（至少在 2025 年第 1 季度之前，系统不会检查广告大小）。
同时定义了 buyerAndSellerReportingId 和 buyerReportingId
如果兴趣群体配置中同时定义了 buyerAndSellerReportingId 和 buyerReportingId：
navigator.joinAdInterestGroup({
owner: 'https://buyer.example',
name: 'example-interest-group',
ads: [{
renderUrl: `https://buyer.example/ad.html`,
buyerReportingId: 'brid123',
buyerAndSellerReportingId: 'bsrid123',
}]
});
然后，由于覆盖行为，在 reportWin() 内只有 buyerAndSellerReportingId 可用：
function reportWin(..., browserSignals, ...) {
const {
buyerAndSellerReportingId, // 'bsrid123'
} = browserSignals;
}
在可供 reportWin() 使用之前，系统会检查 buyerAndSellerReportingId 是否与兴趣群体所有者、出价脚本网址、呈现网址和广告尺寸（广告尺寸至少在 2025 年第 1 季度之前不会纳入此项检查）进行 k-匿名性检查。
buyerAndSellerReportingId 和 buyerReportingId 均未定义
如果兴趣群体配置中均未定义报告 ID：
navigator.joinAdInterestGroup({
owner: 'https://buyer.example',
name: 'example-interest-group',
ads: [{
renderUrl: `https://buyer.example/ad.html`,
}]
});
然后，reportWin() 中就有兴趣群体 name：
function reportWin(..., browserSignals, ...) {
const {
interestGroupName, // 'example-interest-group'
} = browserSignals;
}
在可供reportWin()使用之前，系统会检查兴趣群体名称 (interestGroupName) 与兴趣群体所有者、出价脚本网址、呈现网址和广告尺寸（广告尺寸至少在 2025 年第 1 季度之前不会纳入此检查范围）的 k-匿名性。
可选择的报告 ID
可选择的报告 ID 可让买方在出价生成过程中选择一个 ID，然后浏览器会将所选值提供给 scoreAd() 和报告功能。selectableBuyerAndSellerReportingIds 值（一个字符串数组）会提供给 generateBid()，买方可以将一个选定的 ID 作为 selectedBuyerAndSellerReportingId 返回。
generateBid() 和 scoreAd() 函数将针对兴趣群体配置中定义的每个广告运行，并接收每个广告的报告 ID。买方和卖方报告功能仅会针对胜出的广告运行，并且这些函数将收到为该胜出广告定义的报告 ID。
当不可选择的报告 ID 与可选择的报告 ID 结合使用时，这些 ID 的行为不同于上一节介绍的工作流程。与不可选择的报告 ID 只能在报告函数内使用的初始行为不同，可选择的报告 ID 让不可选择的报告 ID 也能在 generateBid() 和 scoreAd() 中使用。
兴趣群体
可选报告 ID 字段 selectableBuyerAndSellerReportingIds 是买方为广告的兴趣组定义的字符串数组。除可选报告 ID 外，您还可以定义不可选择的报告 ID：
navigator.joinAdInterestGroup({
owner: 'https://buyer.example',
name: 'example-interest-group',
ads: [{
renderUrl: `https://buyer.example/ad.html`,
buyerReportingId: 'brid123',
buyerAndSellerReportingId: 'bsrid123',
selectableBuyerAndSellerReportingIds: ['sbsrid1', 'sbsrid2', 'sbsrid3']
}]
});
生成买方出价
如果在兴趣群组配置中定义了 selectableBuyerAndSellerReportingIds，则它会与定义的其他报告 ID 一起在 generateBid() 中提供。
function generateBid(..., browserSignals, ...) {
const {
buyerReportingId, // 'brid123'
buyerAndSellerReportingId, // 'bsrid123'
selectableBuyerAndSellerReportingIds // ['sbsrid1', 'sbsrid2', 'sbsrid3']
} = browserSignals;
return {
bid: 1,
render: 'https://buyer.example/ad.html',
selectedBuyerAndSellerReportingId: 'sbsrid2' // Buyer returns the selected ID
};
}
买方可以从 generateBid() 中的 selectableBuyerAndSellerReportingIds 数组中选择一个 ID，并将所选 ID 作为 selectedBuyerAndSellerReportingId 返回。如果所选值不在 selectableBuyerAndSellerReportingIds 数组中，系统会拒绝出价。如果在兴趣群体配置中指定了 selectableBuyerAndSellerReportingIds，并且买方未从 generateBid() 返回 selectedBuyerAndSellerReportingId，那么报告 ID 将恢复为不可选择的报告 ID 所描述的行为。
仅当 selectedbuyerAndSellerReportingId 的值与 buyerAndSellerReportingId（如果存在）、buyerReportingId（如果存在）、兴趣群体所有者、出价脚本网址、呈现网址和广告尺寸（至少在 2025 年第 1 季度之前，广告尺寸都不会被纳入此检查范围）同时 k-匿名时，返回 selectedbuyerAndSellerReportingId 的出价才可能在竞价中胜出。
卖方广告评分
对于卖方，买方从 generateBid() 返回的 selectedBuyerAndSellerReportingId 将显示在 scoreAd() 中；如果在兴趣群体配置中指定了 buyerAndSellerReportingId，则这些数据同样会在 buyerAndSellerReportingId 中使用。
function scoreAd(..., browserSignals, ...) {
const {
buyerAndSellerReportingId, // 'bsrid123'
selectedBuyerAndSellerReportingId, // 'sbsrid2'
} = browserSignals;
// ...
}
卖方报告
对于卖方报告，买方从 generateBid() 返回的 selectedBuyerAndSellerReportingId 既可在 reportResult() 中使用，也可在 buyerAndSellerReportingId 中使用（如果在兴趣群体中定义）。
function reportResult(..., browserSignals, ...) {
const {
buyerAndSellerReportingId, // 'bsrid123'
selectedBuyerAndSellerReportingId // 'sbsrid2'
} = browserSignals;
// ...
}
如果在兴趣群体配置中指定了 selectableBuyerAndSellerReportingIds，并且 generateBid() 返回了 selectedBuyerAndSellerReportingId，除非 selectedBuyerAndSellerReportingId 和 buyerAndSellerReportingId（如果存在）与兴趣群体所有者、出价脚本网址、呈现网址和广告尺寸（广告尺寸至少在 2025 年第 1 季度之前不会纳入此检查范围）进行了 k-匿名化，并且系统不会为该出价执行 reportResult()，否则将无法在竞价中胜出。因此，如果使用 selectedBuyerAndSellerReportingId 的值调用 reportResult()，则表示报告 ID 通过了 k-匿名性检查，并且 reportResult() 中将可用定义的所有报告 ID。
买家报告
如果在兴趣群体配置中定义了 selectableBuyerAndSellerReportingIds，并且从 generateBid() 返回了 selectedBuyerAndSellerReportingId，则兴趣群体配置中定义的报告 ID 均可供使用。请注意，与卖方报告类似，如果报告 ID 不是 k-匿名化，则无法赢得竞价，并且不会针对该出价运行 reportWin()。
function reportWin(..., browserSignals, ...) {
const {
buyerReportingId, // 'brid123'
buyerAndSellerReportingId, // 'bsrid123'
selectedBuyerAndSellerReportingId // 'sbsrid2'
} = browserSignals;
// ...
}
覆盖规则
下面我们总结了针对不可选择的报告 ID 和可选择的报告 ID 的覆盖规则。传递到 reportWin() 的 selectableBuyerAndSellerReportingIds、buyerAndSellerReportingId、buyerReportingId 和兴趣群体名称是由浏览器确定的，其逻辑如下：
- 如果出价返回
selectedBuyerAndSellerReportingId，则selectedBuyerAndSellerReportingId、buyerAndSellerReportingId（如果在兴趣组中定义）和buyerReportingId（如果在兴趣组中定义）均可用于报告。 - 否则，如果在兴趣群体中定义了
buyerAndSellerReportingId，则只有buyerAndSellerReportingId可用于报告。 - 否则，如果在兴趣群体中定义了
buyerReportingId，则报告中只会显示buyerReportingId。 - 否则，只有兴趣群体
name可生成报告。
下表介绍了覆盖行为：
| 报告 ID 是否在兴趣群体配置中定义？ | 可用的报告 ID | |||
selectableBuyerAnd
|
buyerAndSeller
|
buyerReportingId
|
reportWin()
|
reportResult()
|
是，并且已选择“generateBid()”中的“” |
可选 | 可选 |
1) selectableBuyerAnd2) buyerAndSeller（如果已定义）3) buyerReportingId（如果已定义）
|
1) selectableBuyerAnd2) buyerAndSeller（如果已定义） |
否，或未在generateBid()中选择 |
是 | 已忽略 | buyerAndSeller |
buyerAndSeller |
否，或未在generateBid()中选择 |
否 | 是 | buyerReportingId |
无 |
否，或未在“generateBid()”中选择 |
否 | 否 | interestGroupName |
无 |
互动和分享反馈
- 如需详细了解报告 ID，请参阅 Protected Audience 说明文档的“报告 ID”部分。
- GitHub：在 API 代码库中提出问题并关注讨论。
- W3C：在 WICG 通话中讨论行业用例。
- 通告：加入或查看邮寄名单。
- Privacy Sandbox 开发者支持：您可以在 Privacy Sandbox 开发者支持仓库中提问和参与讨论。
- Chromium：提交 Chromium 错误，提出有关可在 Chrome 中测试的实现方面的问题。