了解如何配置 Protected Audience API 竞价。
卖方进行的设备端竞价
设备端 Protected Audience 竞价在销售广告空间的网站上运行,我们将进行竞价的一方称为卖方。许多方可能充当卖方:网站可能会自行开展广告竞价,也可能包含第三方脚本来为其竞价,或者使用将设备端竞价与其他服务器端广告竞价活动相结合的 SSP。在设备端广告竞价中,卖方需要完成三项基本工作:
- 卖方决定 (a) 哪些买方可以参与,以及 (b) 这些买方兴趣群体中的哪些出价有资格参与竞价。这样,卖方就能够执行网站的规则,来决定允许哪些广告在网页上展示。
- 卖方负责竞价的业务逻辑:一种 JavaScript 代码,它会考虑每个出价的价格和元数据,并计算“可期性”得分。理想性得分最高的出价会赢得竞价。
- 卖方对竞价结果进行报告,包括有关清算价格和任何其他付款的信息。胜出和落败买方也可以生成自己的报告。
本文档将介绍如何配置和发起设备端竞价。
配置 Protected Audience API 广告竞价
为了运行 Protected Audience API 广告竞价,首先要配置竞价。可以通过创建 auctionConfig
对象来做到这一点。以下是此类配置的一个示例:
const auctionConfig = {
seller: 'https://seller.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://buyer-1.example', 'https://buyer-2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://buyer-1.example': {...},
'https://buyer-2.example': {...},
...
},
perBuyerTimeouts: {
'https://buyer-1.example': 50,
'https://buyer-2.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://component-seller.example',
'decisionLogicUrl': ...,
...
},
...
],
resolveToConfig: [true|false],
};
AuctionConfig
个房源
必要属性
auctionConfigs
的唯一必需属性是 seller
、decisionLogicUrl
和 interestGroupBuyers
。
媒体资源 | 示例 | 角色 |
---|---|---|
seller | https://seller.example | 卖家的来源。 |
decisionLogicUrl | https://seller.example/decision-logic.js | 竞价 JavaScript 决策逻辑 Worklet 的网址。此字段必须与卖方字段具有相同的来源。 |
interestGroupBuyers | [https://buyer-1.example, https://buyer-2.example, ...] |
所有兴趣群体所有者被请求参与竞价的出处 |
可选属性
auctionConfigs
的其余属性是可选的。
异步提供信号
某些信号(由 auctionSignals
、sellerSignals
、perBuyerSignals
和 perBuyerTimeouts
字段配置的信号)的值可以选择不作为具体值提供,而是作为 promise 提供。这样一来,竞价的某些部分(例如加载脚本和可信信号以及启动隔离的 Worklet 进程)可以与这些值的计算(或网络检索)重叠。Worklet 脚本只能看到已解析的值;如果任何此类 Promise 被拒绝,竞价将被取消,除非竞价已失败或以其他方式被取消。
配置由多个卖方参与的竞价
在某些情况下,多个卖方可能想要参与竞价,单独竞价的胜出者会传递到由另一个卖方进行的另一场竞价。跳过的这些单独的竞价称为组成部分竞价。
为便于完成这些组件竞价,componentAuctions
对象可以包含每个卖方的组件竞价的其他竞价配置。所有这些竞价的胜出出价都将进入“顶级”竞价,最终决定竞价。组件竞价的 auctionConfig
可能没有自己的 componentAuctions
。当 componentAuctions
不为空时,interestGroupBuyers
必须为空。也就是说,对于任何特定的 Protected Audience 竞价,要么只有一个卖方竞价,没有组成部分竞价,要么所有出价都来自组成部分竞价,顶级竞价只能在组成部分竞价的胜出者中进行选择。
开展竞价
卖方通过调用 navigator.runAdAuction()
向用户浏览器发出开始广告竞价的请求。
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
runAdAuction()
调用会返回一个解析为广告的 Promise。发布商网页上的任何代码都无法检查胜出的广告或以其他方式从 runAdAuction()
结果了解其内容。如果在 AuctionConfig
中将 resolveToConfig
标志设置为 true,则返回 FencedFrameConfig
对象,该对象只能在围栏帧中呈现。如果该标志设置为 false,则会返回可在 iframe 中呈现的不透明 URN。runAdAuction 可能会返回 null 值,表示未选择任何广告。在这种情况下,卖方可能会选择展示内容相关广告。