卖方指南：开展广告竞价

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

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

全面了解开发者指南 请参阅 Protected Audience API 说明文档，以深入讨论 卖方如何进行设备端竞价。

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

什么是 Protected Audience API 广告竞价？

Protected Audience API 广告竞价是一系列小型 JavaScript 程序， 浏览器会在用户设备上运行，以选择广告。为保护隐私， 卖方和买方提供的竞价代码在独立的 JavaScript 中运行 worklet：无法与

<ph type="x-smartling-placeholder">
</ph> <ph type="x-smartling-placeholder"></ph> Protected Audience API 广告竞价的六个阶段
此图概述了 Protected Audience API 广告竞价的每个阶段。
  1. 用户访问一个展示广告的网站。
  2. 卖方的代码执行 navigator.runAdAuction()。该参数指定了 可供销售的广告空间以及出价的竞争者。卖方还必须添加脚本 为各个出价都指定了高分：scoreAd()。
  3. 执行受邀买方的代码，以便为相关广告生成出价和网址 广告素材和其他数据出价脚本可以查询实时数据， （例如，广告系列的剩余预算） 键值对服务。
  4. 卖方代码会为每次出价评分并选择胜出者。此逻辑使用 出价值和其他数据返回出价的可接受程度。无法胜出的广告 内容相关胜出者被拒。卖方可以使用自己的 键值对服务：适用于实时数据。
  5. 胜出的广告以不透明值的形式返回，该值显示在 fenced frame：卖方和 发布商将无法查看此值。
  6. 系统会将竞价报告给卖方和胜出的买方。

竞价何时进行？

Protected Audience API 可以单独运行，也可以与程序化竞价一起运行。在多卖家模式中 程序化竞价：

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

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

Protected Audience API 广告竞价由谁开展？

可能会有多个竞价方通过竞价来销售广告空间。

例如：

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

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

  • 强制执行发布商规则：哪些买方和哪些出价符合条件。
  • 运行竞价逻辑：JavaScript 在以下位置运行： worklets 用于计算 各个出价的受欢迎程度得分
  • 报告竞价结果。

这些作业通过卖方提供的代码以编程方式完成 通过调用 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 可解析为表示URNurn: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() 函数中添加逻辑，浏览器会在一个 Worklet 中执行该函数，该 Worklet 与外部代码的通信有限。浏览器本身不会为广告评分。浏览器负责执行评分逻辑并选择得分最高的出价。

所有 Protected Audience API 参考文档

以下是 API 参考指南：

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