关于生成 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 开发者指南。
- 有关 Protected Audience 兴趣群体和出价生成的广告买方指南。
- Protected Audience 广告竞价广告卖方指南。
- 关于报告竞价结果的指南
- Protected Audience 广告竞价延迟时间方面的最佳实践
- 对 Protected Audience 进行问题排查
Protected Audience API 说明信息还详细介绍了功能支持和限制条件。
后续操作
我们希望与您交流,确保我们构建适合所有人的 API。
讨论 API
与其他 Privacy Sandbox API 一样,此 API 也会记录在案并公开讨论。
使用 API 进行实验
您可以进行实验并参与有关 Protected Audience API 的对话。