卖方指南：开展广告竞价

适用于 Protected Audience API 广告竞价的 Seller API 指南和参考文档。

在本文中，您将找到广告竞价的技术参考，该参考信息适用于实验性 Protected Audience API 的当前迭代。

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

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

什么是 Protected Audience API 广告竞价？

Protected Audience API 广告竞价是一系列小型 JavaScript 程序的集合，浏览器会在用户设备上运行以选择广告。为了保护隐私，来自卖方和买方的所有广告竞价代码都在无法与外部环境进行通信的独立 JavaScript 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() 会返回一个解析为表示广告竞价结果的 URN (urn:uuid:<something>) 的 promise。只有在传递到围栏框架进行呈现时，浏览器才能对它进行解码：发布商网页无法检查胜出的广告。

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() 函数中添加逻辑，浏览器在 Worklet 中执行该函数，此 Worklet 与其外部代码进行通信。浏览器本身不会给广告评分。浏览器全权负责执行评分逻辑，并选择得分最高的出价。

所有 Protected Audience API 参考文档

以下是 API 参考指南：

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