生成 Protected Audience API 竞价结果报告

卖方和买方指南：生成 Protected Audience API 竞价报告。

本文是一篇技术参考文章，介绍了如何生成 Protected Audience API 竞价胜出的报告，这些报告用于当前迭代的实验性 Protected Audience API。

如需了解 Protected Audience API 的完整生命周期，请阅读开发者指南；如需深入探讨事件级报告（临时），请参阅 Protected Audience API 说明。

不是开发者？请参阅 Protected Audience API API 概览。

Protected Audience API 会报告哪些内容？

目前有以下两种 Protected Audience API 报告：

  • 卖方报告：告知卖方广告竞价的胜出者。
  • 买方报告：仅适用于胜出的买方，用于了解他们赢得了竞价。

长期计划是允许浏览器使用 Private Aggregation API 向卖家和买家报告竞价结果。作为一种临时的事件级报告机制，为卖方实现 reportResult() 的代码和为中标方实现 reportWin() 的代码可以调用 sendReportTo() 函数。此函数接受一个实参：一个字符串，表示竞价结束后提取的网址，其中包含要报告的事件级信息。

API 功能

卖家：reportResult()

decisionLogicUrl 中提供的卖方 JavaScript（也提供 scoreAd()）可以包含一个 reportResult() 函数，用于报告竞价结果。

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

传递给此函数的实参如下：

auctionConfig

传递给 navigator.runAdAuction() 的竞价配置对象。

browserSignals

由浏览器构建的对象，提供有关竞价的信息。 例如：

  {
    'topWindowHostname': 'publisher.example',
    'interestGroupOwner': 'https://dsp.example',
    'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
    'bid': <bidValue>,
    'desirability': <winningAdScore>
  }

此函数的返回值会用作胜出竞标者的 reportWin() 函数的 sellerSignals 实参。

买方：reportWin()

胜出出价者的 JavaScript（也提供了 generateBid()）可以包含一个 reportWin() 函数来报告竞价结果。

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

传递给此函数的实参如下：

auctionSignals和perBuyerSignals

传递给中标者的 generateBid() 的值相同。

sellerSignals

reportResult() 的返回值，让卖家有机会向买家传递信息。

browserSignals

由浏览器构建的对象，提供有关竞价的信息。 例如：

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid': <bidValue>
}

临时报告实现

Chrome 中暂时提供两种竞价报告方法：

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

这些方法各自接受一个实参：竞价完成后要提取的网址。它们可以在 scoreAd() 和 generateBid() 中多次调用，并使用不同的网址实参。

只有当竞价顺利完成时，Chrome 才会发送调试失败/胜出报告。如果竞价被取消（例如，由于新导航），则不会生成任何报告。

当您在 chrome://settings/adPrivacy 下启用所有广告隐私权 API 时，这些方法在 Chrome 中默认可用。如果您运行 Chrome 时使用了命令行标志来启用 Protected Audience API，则需要通过添加 BiddingAndScoringDebugReportingAPI 标志来明确启用这些方法。如果未启用该标志，这些方法仍可使用，但不会执行任何操作。

所有 Protected Audience API API 参考

以下是 API 参考指南：

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

后续操作

我们希望与您交流，确保我们构建适合所有人的 API。

讨论 API

与其他 Privacy Sandbox API 一样，此 API 也会记录在案并公开讨论。

使用 API 进行实验

您可以进行实验并参与有关 Protected Audience API 的对话。