了解如何配置 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
的其余属性是可选的。
属性 | 示例 | 角色 |
---|---|---|
trustedScoringSignalsUrl | https://seller.example/scoring-signals | 卖方的键值对服务器的网址。在广告评分过程中,系统会使用广告素材的呈现网址作为键来查询此值。此字段必须与卖方字段具有相同的来源。 |
auctionSignals | {"category":"news"} | 可序列化的 JSON 对象,表示所有参与竞价的买方和卖方可用的信号。 |
sellerSignals | {...} | JSON 可序列化对象,表示仅供卖方使用的信号。 |
perBuyerSignals | {https://dsp.example: {...}, https://another-buyer.example: {...}, ... } |
可供特定买方使用的信号。信号可能来自卖方,也可能来自买方本身。 |
perBuyerTimeouts | {https://www.example-dsp.com: 50, https://www.another-buyer.com: 200, *:150、 ...}, |
特定买方的 generateBid() 脚本的运行时间上限(以毫秒为单位)。系统会对每个未定义具体超时的买方应用一个通配符。 |
sellerTimeout | 100 | 卖方 scoreAd() 脚本的最长运行时(以毫秒为单位)。 |
componentAuctions | [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] | 组件竞价的其他配置。 |
resolveToConfig | true|false | 一个布尔值,用于从 runAdAuction() 返回的 promise 指向 true (在 <fencedframe> 中使用)解析为 FencedFrameConfig,或在 false(在 <iframe> 中使用)指向不透明的 urn:uuid 网址。默认值为 false。 |
异步提供信号
某些信号(由 auctionSignals
配置的信号)的值,
sellerSignals
、perBuyerSignals
和 perBuyerTimeouts
字段)可以
可以选择不作为具体值提供,而是以 Promise 的形式提供。如此一来,
竞价的某些部分,例如加载脚本和可信信号;以及
启动隔离的 Worklet 进程,
检索)。Worklet 脚本将只看到解析的
值;如果任何此类 Promise 被拒绝,则将会取消竞价,除非它
已失败,或者以其他方式被中止。
配置涉及多个卖方的竞价
在某些情况下,可能有多个卖方想要参与竞价,
单独竞价的胜出者被交由另一场竞价
卖家。这些相互传递的竞价称为“部分竞价”。
为方便这些组件竞价,componentAuctions
对象可以包含
为每个卖方的竞价配置提供其他竞价配置。通过
系统会将每个部分竞价的胜出出价 传递给
“顶级”并据此做出最终的竞价决定。通过
auctionConfig
的组成部分竞价可能没有自己的
componentAuctions
。当 componentAuctions
不为空时,
“interestGroupBuyers
”必须为空。也就是说,对于任何特定的受保护的
受众群体竞价,要么只有一个卖方,要么没有组成部分竞价;或者
否则,所有出价都来自部分竞价,顶级竞价只能
从组件竞价中选择。
开展竞价
卖方通过
正在调用 navigator.runAdAuction()
。
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
runAdAuction()
调用会返回解析为广告的 Promise。不是
发布商网页上的任何代码都可以检查胜出的广告,或
否则,将从 runAdAuction()
的结果中获取其内容。如果
在 AuctionConfig
中将 resolveToConfig
标志设置为 true,
返回 FencedFrameConfig
对象,该对象只能在围栏内渲染
帧。如果该标志设置为 false,则系统会返回一个不透明的 URN,
呈现在 iframe 中。runAdAuction 会返回 null 值,
表示未选择任何广告。在这种情况下,卖方可以选择
如何呈现内容相关广告。