生成 Protected Audience API 竞价结果报告

有关如何生成 Protected Audience API 竞价报告的卖方和买方指南。

本文是用于生成 Protected Audience API 竞价胜出情况报告的技术参考，与实验性 Protected Audience API 的当前迭代版本相同。

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

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

Protected Audience API 会报告什么内容？

Protected Audience API 报告有两种：

  • 卖方报告：告知卖方广告竞价胜出者。
  • 买方报告：仅向胜出的买方提供，用于了解自己是否赢得了竞价。

长期计划是让浏览器使用 Private Aggregation API 报告卖方和买方的竞价结果。作为一种临时的事件级报告机制，为卖方实现 reportResult() 并为胜出出价方实现 reportWin() 的代码可以调用 sendReportTo() 函数。这需要一个参数：一个字符串，表示竞价完成后提取的网址，该参数对要报告的事件级信息进行编码。

API 功能

卖家：reportResult()

decisionLogicUrl（也提供 scoreAd()）中提供的卖方 JavaScript 可包含一个 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 下启用所有 Ad Privacy API 后，Chrome 中会默认提供这些方法。如果您通过命令行标志运行 Chrome 以启用 Protected Audience API，则需要通过添加 BiddingAndScoringDebugReportingAPI 标志来明确启用这些方法。如果未启用该标志，这些方法仍然可用，但不执行任何操作。

所有 Protected Audience API 参考文档

以下是 API 参考指南：

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

后续操作

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

讨论 API

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

使用 API 进行实验

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