卖方指南：开展广告竞价

Protected Audience API 广告竞价的卖方 API 指南和参考文档。

本文中提供了实验性 Protected Audience API 当前迭代中使用的广告竞价的技术参考。

如需了解 Protected Audience API 的整个生命周期，请参阅开发者指南；如需深入了解卖方如何运行设备端竞价，请参阅 Protected Audience API 说明文档。

不是开发者？请参阅 Protected Audience API 概览。

什么是 Protected Audience API 广告竞价？

Protected Audience API 广告竞价是一组小型 JavaScript 程序，浏览器会在用户设备上运行这些程序来选择广告。为保护隐私，卖方和买方的所有广告竞价代码均在隔离的 JavaScript worklet 中运行，这些 worklet 无法与外界通信。

Protected Audience API 广告竞价的六个阶段
此图概述了 Protected Audience API 广告竞价的各个阶段。
  1. 用户访问某个展示广告的网站。
  2. 卖方的代码会执行 navigator.runAdAuction()。这用于指定哪些广告空间待售以及哪些人可以出价。卖方还必须添加用于为每个出价评分的脚本 scoreAd()。
  3. 系统会执行受邀买方的代码，以生成出价、相关广告素材资源的网址和其他数据。出价脚本可以从买方的键值对服务查询实时数据，例如剩余的广告系列预算。
  4. 卖方的代码会为每个出价评分，并选择胜出出价。此逻辑使用出价价值和其他数据来返回出价的吸引力。如果广告无法击败内容相关广告胜出方，则会被拒登。卖方可以使用自己的键值对服务来处理实时数据。
  5. 胜出的广告会作为不透明值返回，并显示在围栏框架中。卖方和发布商都无法查看此值。
  6. 系统会向卖方和胜出的买方报告竞价结果。

竞价何时进行？

Protected Audience API 可以单独运行，也可以与程序化竞价结合使用。在多卖方程序化竞价中：

  1. 用户访问参与计划的网站。
  2. 另一个卖方会运行程序化竞价，以便为可用的广告位找到相应的内容相关广告。
  3. 运行 Protected Audience API 竞价。
  4. scoreAd()将买方的出价与第一次竞价的结果进行比较。

无法击败内容相关广告胜出者的出价会被拒绝。

谁负责运行 Protected Audience API 广告竞价？

可能会有多个方开展竞价来出售广告空间。

例如：

  • 内容发布商：自行在其网站上托管广告内容。
  • 供应方平台 (SSP)：与发布商合作并提供其他服务。
  • 第三方脚本：代表发布商参与广告竞价。

使用 Protected Audience API 时，卖方有三项工作：

  • 强制执行发布商规则：哪些买方和哪些出价符合条件。
  • 运行竞价逻辑：在 worklet 中运行 JavaScript 以计算每个出价的吸引力得分。
  • 报告竞价结果。

这些作业是通过程序化方式完成的，卖方在通过调用 JavaScript 函数 navigator.runAdAuction() 发起广告竞价时，会在其提供的代码中完成这些作业。

API 功能

runAdAuction()

卖方通过调用 navigator.runAdAuction() 向用户的浏览器发出请求，以启动广告竞价。

例如：

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

try {
  const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
  // Handle error.
}

runAdAuction() 会返回一个 promise，该 promise 会解析为表示广告竞价结果的 URN (urn:uuid:<something>)。只有在传递到围栏帧进行呈现时，浏览器才能对其进行解码：发布商页面无法检查胜出的广告。

decisionLogicUrl 脚本会逐个考虑每个广告及其关联的出价和元数据，然后为其分配一个数值的偏好度得分。

auctionConfig 个房源

seller
必填
示例：'https://ssp.example'
角色：卖方的来源。
decisionLogicUrl
必需
示例：'https://ssp.example/auction-decision-logic.js'
作用：竞价 worklet JavaScript 的网址。
trustedScoringSignalsUrl
可选
示例：'https://ssp.example/scoring-signals'
作用：卖方的可信服务器的网址。
interestGroupBuyers
必需
示例：['https://dsp.example', 'https://buyer2.example', ...]
角色：所有被要求在竞价中出价的兴趣群体所有者的来源。
注意：卖方可以指定 interestGroupBuyers:，以允许所有兴趣群组出价。然后，系统会根据兴趣群体所有者之外的其他条件来接受或拒绝广告。例如，卖方可能会审核广告素材，以确认其是否符合其政策。
auctionSignals
可选
示例：{...}
作用：包含页面上下文、竞价类型等方面的卖方信息
sellerSignals
可选
示例：{...}
角色：根据发布商设置、发出内容相关广告请求等获取的信息
sellerTimeout
可选
示例：100
作用：卖方的 scoreAd() 脚本的最大运行时（毫秒）。
perBuyerSignals
可选
示例： 
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
角色：来自每个特定买方服务器的与网页相关的情境信号。
perBuyerTimeouts
可选
示例：50
作用：特定买方的 generateBid() 脚本的最大运行时（毫秒）。
componentAuctions
可选
示例： 
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
角色：组件竞价的其他配置。

decisionLogicUrl

decisionLogicUrl 是竞价配置对象的属性，会传递给 runAdAuction()。此网址必须包含 scoreAd() 函数的脚本。系统会针对每个广告运行此逻辑一次，以确定其可取性。

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

browserSignals

browserSignals 是由浏览器构建的对象，其中包含浏览器知道且卖方的竞价脚本可能想要验证的信息：

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}

在竞价开始之前，卖方会为可用的广告位找到最合适的情境广告。scoreAd() 逻辑的一部分会拒绝任何无法击败内容相关广告胜出的广告。

scoreAd()

scoreAd() 接受以下参数：

参数 角色
adMetadata 买方提供的任意元数据。
auctionConfig 传递给 navigator.runAdAuction() 的竞价配置对象。
bid 数值出价。
trustedScoringSignals 在竞价时从卖方的可信服务器检索的值，表示卖方对广告的意见。

常见问题解答

如何确定竞价胜出者？由谁来确定？

卖方提供评分逻辑来确定每个广告的吸引力得分，浏览器会选择得分最高的广告作为胜出广告。

卖方在 scoreAd() 函数中添加逻辑，浏览器在与外部代码通信受限的工作流中执行该函数。浏览器本身不会为广告评分。浏览器负责执行评分逻辑并选择得分最高的出价。

所有 Protected Audience API 参考文档

以下是 API 参考指南：

Protected Audience API 说明信息还详细介绍了功能支持和限制条件。