卖方指南：开展广告竞价

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 中运行。

Protected Audience API 广告竞价的六个阶段
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，卖方可以执行三项任务：

  • 强制执行发布商规则：哪些买方和哪些出价符合条件。
  • 运行竞价逻辑：在工作程序中运行 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'
角色：竞价工作程序的 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 中执行该函数。浏览器本身不会对广告进行评分。浏览器专门负责执行评分逻辑并选择得分最高的出价。

所有 Protected Audience API 参考

以下是 API 参考指南：

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