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