了解报告 ID 在 Protected Audience 竞价中的运作方式
概览
报告 ID 是与广告相关联的标识符，可用于生成出价、对出价进行评分和生成报告。报告 ID 由买方在兴趣群体配置中提供，并会在本指南中所述的各种条件下显示在 generateBid()、scoreAd()、reportResult() 和 reportWin() 中。
借助报告 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() 中可用之前，系统会检查该 ID 是否具有与兴趣群体所有者、出价脚本网址、呈现网址和广告大小的 k-匿名性（至少在 2025 年第 1 季度之前，广告大小将从此检查中排除）。如果不满足 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 是否具有基于兴趣群组所有者、出价脚本网址、呈现网址和广告大小的 k-匿名性（至少在 2025 年第 1 季度之前，系统不会检查广告大小）。
仅定义了 buyerAndSellerReportingId
如果兴趣群组配置中仅定义了 buyerAndSellerReportingId：
navigator.joinAdInterestGroup({
owner: 'https://buyer.example',
name: 'example-interest-group',
ads: [{
renderUrl: `https://buyer.example/ad.html`,
buyerAndSellerReportingId: 'bsrid123',
}]
});
然后，buyerAndSellerReportingId 便可在 reportWin() 中使用：
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 之前，系统会检查 buyerAndSellerReportingId 是否具有基于兴趣群组所有者、出价脚本网址、呈现网址和广告大小的 k-匿名性（至少在 2025 年第 1 季度之前，广告大小将从此检查中排除）。
未定义 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) 之前，系统会检查该名称是否具有 k-匿名性，并考虑兴趣群体所有者、出价脚本网址、呈现网址和广告大小（至少在 2025 年第 1 季度之前，广告大小将从此检查中排除）。
可选择的报告 ID
借助可选择的报告 ID，买方可以在出价生成期间选择 ID，浏览器会将所选值提供给 scoreAd() 和报告函数。selectableBuyerAndSellerReportingIds 值（一个字符串数组）会提供给 generateBid()，买方可以将一个选定的 ID 作为 selectedBuyerAndSellerReportingId 返回。
generateBid() 和 scoreAd() 函数将针对兴趣群体配置中定义的每个广告运行，并接收每个广告的报告 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(interestGroup, ...) {
const [{
buyerReportingId, // 'brid123'
buyerAndSellerReportingId, // 'bsrid123'
selectableBuyerAndSellerReportingIds // ['sbsrid1', 'sbsrid2', 'sbsrid3']
}] = interestGroup.ads;
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（如果在兴趣群体中定义了 buyerAndSellerReportingId）。
function reportResult(..., browserSignals, ...) {
const {
buyerAndSellerReportingId, // 'bsrid123'
selectedBuyerAndSellerReportingId // 'sbsrid2'
} = browserSignals;
// ...
}
如果在兴趣群体配置中定义了 selectableBuyerAndSellerReportingIds，并且 generateBid() 返回了 selectedBuyerAndSellerReportingId，则除非 selectedBuyerAndSellerReportingId 和 buyerAndSellerReportingId（如果有）与兴趣群体所有者、出价脚本网址、呈现网址和广告大小（至少在 2025 年第 1 季度之前，广告大小将从此检查中排除）具有 k-匿名性，并且系统不会针对该出价执行 reportResult()，否则该出价将无法赢得竞价。因此，如果使用 selectedBuyerAndSellerReportingId 的值调用 reportResult()，则表示报告 ID 通过了 k-匿名性检查，并且定义的所有报告 ID 都将在 reportResult() 内可用。
买方报告
如果在兴趣群组配置中定义了 selectableBuyerAndSellerReportingIds，并且从 generateBid() 返回了 selectedBuyerAndSellerReportingId，则兴趣群组配置中定义的所有报告 ID 都会变为可用状态。请注意，与卖方报告类似，如果报告 ID 不具有 k-匿名性，则无法赢得竞价，并且 reportWin() 不会针对该出价运行。
function reportWin(..., browserSignals, ...) {
const {
buyerReportingId, // 'brid123'
buyerAndSellerReportingId, // 'bsrid123'
selectedBuyerAndSellerReportingId // 'sbsrid2'
} = browserSignals;
// ...
}
覆盖规则
下面总结了不可选择的报表 ID 和可选择的报表 ID 的覆盖规则。selectableBuyerAndSellerReportingIds、buyerAndSellerReportingId、buyerReportingId 和兴趣群组名称中的哪个值会传递给 reportWin()，由浏览器根据以下逻辑确定：
- 如果出价返回
selectedBuyerAndSellerReportingId，则selectedBuyerAndSellerReportingId、buyerAndSellerReportingId（如果在兴趣群组中定义）和buyerReportingId（如果在兴趣群组中定义）均可用于报告。 - 否则，如果在兴趣群体中定义了
buyerAndSellerReportingId，则报告中仅会显示buyerAndSellerReportingId。 - 否则，如果在兴趣群体中定义了
buyerReportingId，则只有buyerReportingId可用于生成报告。 - 否则，系统只会针对兴趣群组
name生成报告。
下表介绍了覆盖行为：
| 报告 ID 是否在兴趣群组配置中定义？ | 可用的报告 ID | |||
selectableBuyerAnd
|
buyerAndSeller
|
buyerReportingId
|
reportWin()
|
reportResult()
|
是，并在 generateBid() 中选择了 |
可选 | 可选 |
1) selectedBuyerAnd2) buyerAndSeller（如果已定义）3) buyerReportingId（如果已定义）
|
1) selectedBuyerAnd2) buyerAndSeller（如果已定义） |
generateBid() 中为“否”或“未选择” |
是 | 已忽略 | buyerAndSeller |
buyerAndSeller |
generateBid() 中为“否”或未选中 |
否 | 是 | buyerReportingId |
无 |
否，或未在 generateBid() 中选择 |
否 | 否 | interestGroupName |
无 |
互动和分享反馈
- 如需详细了解报告 ID，请参阅“Protected Audience 说明”的“报告 ID”部分。
- GitHub：在 API 代码库中提出问题并跟进问题讨论。
- W3C：在 WICG 通话中讨论行业用例。
- 通告：加入或查看邮寄名单。
- Privacy Sandbox 开发者支持：在 Privacy Sandbox 开发者支持代码库中提问和参与讨论。
- Chromium：提交 Chromium bug，询问可在 Chrome 中测试的实现相关问题。