生成 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 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://flags/#privacy-sandbox-ads-apis，默认情况下，这些方法在 Chrome 中可用。但是，如果您使用命令行 flag 运行 Chrome，以启用 Protected Audience API，则需要添加 BiddingAndScoringDebugReportingAPI 标志来明确启用相应方法。如果未启用该标志，相应方法仍然可用，但不执行任何操作。

所有 Protected Audience API 参考文档

以下是 API 参考指南：

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

后续操作

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

讨论 API

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

使用 API 进行实验

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