报告 ID

了解报告 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}`);
}

在 reportResult() 中提供 ID 之前，系统会检查该 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 年第一季度之前，广告尺寸不会纳入此检查范围）。

仅定义了 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 年第一季度之前，广告尺寸不会纳入此检查范围）。

同时定义了 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 是否具有 k-匿名性，检查对象包括兴趣组所有者、出价脚本网址、呈现网址和广告尺寸（至少在 2025 年第一季度之前，广告尺寸不会纳入此检查范围）。

未定义 buyerAndSellerReportingId 和 buyerReportingId

如果兴趣组配置中未定义任何报告 ID：

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
  }]
});

然后，兴趣群体 name 在 reportWin() 内可用：

function reportWin(..., browserSignals, ...) {
  const {
    interestGroupName, // 'example-interest-group'
  } = browserSignals;
}

在可供 reportWin() 使用之前，系统会检查兴趣组名称 (interestGroupName) 是否具有 k-匿名性，检查对象包括兴趣组所有者、出价脚本网址、呈现网址和广告尺寸（至少在 2025 年第 1 季度之前，广告尺寸不会纳入此检查范围）。

可选择的报告 ID

借助可选择的报告 ID，买方可以在出价生成期间选择一个 ID，然后浏览器会将所选值提供给 scoreAd() 和报告函数。selectableBuyerAndSellerReportingIds 值（一个字符串数组）会提供给 generateBid()，买方能够以 selectedBuyerAndSellerReportingId 的形式返回一个所选 ID。

generateBid() 和 scoreAd() 函数将针对兴趣组配置中定义的每个广告运行，并接收每个广告的报告 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(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 的返回值为 ，出价只有在满足以下条件时才能赢得竞价：selectedbuyerAndSellerReportingId 的值与 buyerAndSellerReportingId（如果存在）、buyerReportingId（如果存在）、兴趣组所有者、出价脚本网址、呈现网址和广告尺寸（至少在 2025 年第 1 季度之前，广告尺寸不会纳入此检查）共同实现 k-匿名化。

卖家广告评分

对于卖家，买家从 generateBid() 返回的 selectedBuyerAndSellerReportingId 会在 scoreAd() 中提供，如果兴趣组配置中定义了 buyerAndSellerReportingId，则也会提供。

function scoreAd(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId, // 'sbsrid2'
  } = browserSignals;

  // ...
}

卖家报告

对于卖家报告，买方从 generateBid() 返回的 selectedBuyerAndSellerReportingId 会在 reportResult() 中提供，如果兴趣组中定义了 buyerAndSellerReportingId，也会在 reportResult() 中提供。

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，请参阅 Protected Audience 说明文档的“报告 ID”部分。
• GitHub：在 API 代码库的问题中提出问题并关注讨论。
• W3C：在 WICG 通话中讨论行业用例。
• 公告：加入或查看邮寄名单。
• Privacy Sandbox 开发者支持：在 Privacy Sandbox 开发者支持代码库中提问和参与讨论。
• Chromium：提交 Chromium bug，询问有关可在 Chrome 中测试的实现的问题。