作为广告买方(DSP 和广告客户),您可能有兴趣参与发布商网站上的 Protected Audience 广告竞价,以便将广告定位到您在广告客户网站上定义的兴趣群体。通过参与 Protected Audience 竞价,您能够以保护隐私的方式在其他网站上覆盖已确定的客户。
在 Protected Audience 竞价中,您需要提供用于生成出价的逻辑,然后浏览器会使用该逻辑计算出价。这与直接提交出价(而不是提供逻辑)的其他竞价架构形成了鲜明对比。
您需要在 generateBid()
JavaScript 函数中提供出价生成逻辑,该文件会托管在您的服务器上。当您向兴趣群体添加用户时,此文件的位置会作为 biddingLogicUrl
传入兴趣群体配置。
在竞价期间,浏览器会提取 biddingLogicUrl
字段中指定的出价逻辑,并在安全隔离环境中为每个兴趣群体执行 generateBid()
函数,该环境与外部上下文的通信受到限制。执行 generateBid()
时,浏览器会将信号作为参数传递给函数。这些信号包含来自不同来源的各种信息,例如发布商的第一方数据、卖方的数据、实时数据等。您可以使用这些信号来计算出价,generateBid()
调用会返回相应的值。出价提交后,浏览器会对每个出价执行卖方的评分逻辑,以计算卖方的受欢迎程度得分。
generateBid()
下面介绍了 generateBid()
函数的参数以及通过该函数返回的出价结构:
generateBid(interestGroup, auctionSignals, perBuyerSignals,
trustedBiddingSignals, browserSignals, directFromSellerSignals) {
return {
ad: adObject,
adCost: optionalAdCost,
bid: bidValue,
bidCurrency: 'USD',
render: {
url: renderURL,
width: renderWidth,
height: renderHeight
},
adComponents: [
{url: adComponent1, width: componentWidth1, height: componentHeight1},
{url: adComponent2, width: componentWidth2, height: componentHeight2},
// ...
],
allowComponentAuction: false,
modelingSignals: 123 // 0-4095 integer (12-bits)
};
}
参数
generateBid()
接受以下参数:
参数名 | 角色 |
---|---|
|
由广告买方传递的对象。可以使用 dailyUpdateUrl 更新兴趣群体。 |
|
卖方传递给 navigator.runAdAuction() 的竞价配置参数的一个属性。这会提供与网页环境(例如广告尺寸和发布商 ID)、竞价类型(最高出价或次高价格)以及其他元数据相关的信息。 |
|
卖方传递的竞价配置参数的一个属性。如果卖方是向买方服务器执行实时出价调用并将响应传回的 SSP,或者发布商网页直接与买方的服务器联系,这样做可以提供与买方服务器有关的情境信号。如果是,买方可能希望在 generateBid() 中检查这些信号的加密签名,以防遭到篡改。 |
|
一个对象,其键为兴趣群体的 trustedBiddingSignalsKeys ,其值会在 trustedBiddingSignals 请求中返回。 |
|
由浏览器构建的对象,其中可能包括有关网页上下文的信息(例如当前网页的 hostname ,卖方本来可以伪造这些信息)以及兴趣群体本身的数据(例如该群体之前赢得竞价的时间记录,允许设置设备端频次上限)。 |
|
与 auctionSignals 和 sellerSignals 不同,保证来自特定卖方的信号可能来自 runAdAuction 执行环境中的任何参与者。 |
浏览器信号
browserSignals
对象具有以下属性:
{
topWindowHostname: 'publisher.example',
seller: 'https://ssp.example',
topLevelSeller: 'https://www.top-level-ssp.com',
requestedSize: {width: 100, height: 200}, /* if specified in auction config */
joinCount: 3,
recency: 3600000,
bidCount: 17,
prevWinsMs: [[timeDeltaMs1,ad1],[timeDeltaMs2,ad2],...],
wasmHelper: ...
dataVersion: 1,
adComponentsLimit: 40
}
媒体资源 | 说明 |
---|---|
|
进行 runAdAuction() 调用的主机名。 |
|
将出价提交给的卖方。在组件竞价中,此值为组件卖方。 |
|
组件竞价中的顶级卖方,且仅出现在组件竞价中。 |
|
requestedSize 属性会为竞价建议帧大小。卖方在竞价配置中设置请求的尺寸,该值将可供generateBid() 中的出价方使用。参与竞价的出价方可能会为广告选择不同的内容尺寸,系统会直观地将所选尺寸调整为适合相应元素的容器尺寸。 |
|
joinCount 字段是设备在过去 30 天内加入此兴趣群体的次数(在此期间,兴趣群体已持续存储,即设备上没有因离开或成员过期导致该兴趣群体在设备上的存储空间不足)。 |
|
recency 字段是从此设备加入此兴趣群体到现在的时长(以分钟为单位) |
|
此兴趣群体提交出价的次数。 |
|
prevWinMs 字段包含兴趣群体的胜出广告,以及自其上一次胜出以来经过的时间(以毫秒为单位)。请注意,此处的广告对象仅包含 renderURL 和元数据字段。 |
|
一个 WebAssembly.Module 对象(基于兴趣组的 biddingWasmHelperURL )。 |
|
买方键值对服务响应中的数据版本值。 |
|
generateBid() 可以返回的广告组成部分数量上限 |
计算出价
为了计算出价金额,generateBid()
中的代码可以使用函数参数的属性。
例如:
function generateBid(interestGroup, auctionSignals, perBuyerSignals,
trustedBiddingSignals, browserSignals) {
return {
// ...
bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
// ...
}
}
返回出价
generateBid()
会返回具有以下属性的对象:
媒体资源 | 角色 |
---|---|
ad |
有关广告的任意元数据,例如卖方预计可以了解到的有关此出价或广告素材的信息。卖方会在其竞价和决策逻辑中使用这些信息。 |
adCost |
一个数值,用于将报告中的广告客户点击或转化费用从 generateBid 传递到 reportWin。此数值的精度不得超过 8 位尾数和 8 位指数,并且会随机执行舍入。 |
adComponents |
可选列表,包含由多个部分组成的广告的最多 20 个组件,取自传递到 navigator.joinAdInterestGroup() 的兴趣群体参数的 adComponents 属性。 |
allowComponentAuction |
指示此出价是否可以用于组成部分竞价的布尔值。如果未指定,则默认为“false”。 |
bid |
将参与竞价的出价金额。卖方必须能够比较不同买方的出价,因此出价必须采用卖方选择的单位(例如“USD”)。如果出价为零或负数,则此兴趣群体根本不会参与卖方的竞价。通过这种机制,买方可以实施任何广告客户规则,指定其广告可以展示的位置,也可以不展示他们的广告。 |
bidCurrency |
出价所用的币种,用于检查货币。 |
render |
描述在此出价赢得竞价时应呈现的广告素材的字典。其中包括:
|
|
传递给 reportWin() 的一个 0-4095 整数(12 位),包含噪声,如噪声和分桶方案中所述。无效值(例如负值、无限值和 NaN 值)将被忽略,并且不会传递。只会传递最低 12 位。买方可以使用 generateBid() 函数中提供的信号(包括在userBiddingSignals 创建兴趣组时捕获的第一方买方数据)来得出某个值,该值会传递到买方的胜出报告函数,以启用机器学习模型训练。 |