报告 ID

了解报告 ID 在 Protected Audience 竞价中的工作原理

概览

报告 ID 是与广告相关联的标识符，可用于生成出价、对出价进行评分以及生成报告。报告 ID 由买方在兴趣群体配置中提供，在本指南中讨论的各种条件下，这些 ID 都会出现在 generateBid()、scoreAd()、reportResult() 和 reportWin() 中。

通过报告 ID，您可以报告广告的标识符，也可以使用报告 ID 来满足交易等使用情形。

<ph type="x-smartling-placeholder"></ph>

报告 ID 的适用范围

报告 ID 分为以下两种类型：

• 报告 ID 不可选择
  • buyerReportingId（字符串）
  • buyerAndSellerReportingId（字符串）
• 可选择的报告 ID
  • selectableBuyerAndSellerReportingIds（字符串数组）

报告 ID 的行为方式因是否使用了可选择的报告 ID 而异。如果仅使用不可选择的报告 ID，则这些 ID 仅在报告函数内可用。如果使用了可选择的报告 ID 以及不可选择的报告 ID（如果需要的话），那么定义的所有 ID 同样可以在 generateBid() 和 scoreAd() 中使用。

重要提示 ：报告 ID 需要先检查 k-匿名性，然后才能在报告函数（reportResult() 和 reportWin()）中使用。

报告 ID 不可选择

可供选择的报告 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

<ph type="x-smartling-placeholder"></ph>

报告 ID 的可用性（带有可选报告 ID）

可选择的报告 ID 可让买方在出价生成过程中选择一个 ID，然后浏览器会将所选值提供给 scoreAd() 和报告功能。selectableBuyerAndSellerReportingIds 值（一个字符串数组）会提供给 generateBid()，买方可以将一个选定的 ID 作为 selectedBuyerAndSellerReportingId 返回。

generateBid() 和 scoreAd() 函数将针对兴趣群体配置中定义的每个广告运行，并接收每个广告的报告 ID。买方和卖方报告功能仅会针对胜出的广告运行，并且这些函数将收到为该胜出广告定义的报告 ID。

当不可选择的报告 ID 与可选择的报告 ID 结合使用时，这些 ID 的行为不同于上一节介绍的工作流程。与不可选择的报告 ID 只能在报告函数内使用的初始行为不同，可选择的报告 ID 让不可选择的报告 ID 也能在 generateBid() 和 scoreAd() 中使用。

注意 ：自 M130 起，稳定版中将提供可供选择的报告 ID。在可选的报告 ID 达到“稳定”版本之前，您可以通过在命令行中使用标志 --enable-privacy-sandbox-ads-apis --disable-features=EnforcePrivacySandboxAttestations --enable-features=ProtectedAudienceDealsSupport

启动 Canary M130 来对其进行测试

兴趣群体

可选报告 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 的出价才可能在竞价中胜出。

注意 ：如果因初始调用没有为通过 k-匿名性检查的广告生成任何出价而重新运行 generateBid()，则在重新运行时，未通过 k-匿名性检查的 selectableBuyerAndSellerReportingId 不会显示在兴趣组中。

卖方广告评分

对于卖方，买方从 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 SellerReportingIds	buyerAndSeller ReportingId	buyerReportingId	reportWin()	reportResult()
是，并且已选择“generateBid()”中的“ ”	可选	可选	1) selectableBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId（如果已定义） 3) buyerReportingId（如果已定义）	1) selectableBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId（如果已定义）
否，或未在generateBid()中选择	是	已忽略	buyerAndSeller ReportingId	buyerAndSeller ReportingId
否，或未在generateBid()中选择	否	是	buyerReportingId	无
否，或未在“generateBid()”中选择	否	否	interestGroupName	无

互动和分享反馈

• 如需详细了解报告 ID，请参阅 Protected Audience 说明文档的“报告 ID”部分。
• GitHub：在 API 代码库中提出问题并关注讨论。
• W3C：在 WICG 通话中讨论行业用例。
• 通告：加入或查看邮寄名单。
• Privacy Sandbox 开发者支持：您可以在 Privacy Sandbox 开发者支持仓库中提问和参与讨论。
• Chromium：提交 Chromium 错误，提出有关可在 Chrome 中测试的实现方面的问题。