在发布商页面上设置广告竞价

了解如何配置 Protected Audience API 竞价。

由卖家在设备上进行的竞价

设备端 Protected Audience 竞价在销售广告空间的网站上运行，我们将运行竞价的一方称为卖方。许多方都可以充当卖方：网站可以自行运行广告竞价，也可以包含第三方脚本来代为运行竞价，还可以使用 SSP 将运行设备端竞价与其他服务器端广告竞价活动相结合。在设备端广告竞价中，卖方有三项基本工作：

卖家可以决定 (a) 哪些买家可以参与竞价，以及 (b) 这些买家的兴趣群体中的哪些出价有资格参与竞价。这样一来，卖家就可以强制执行网站的规则，以确定允许在网页上展示哪些广告。
卖家负责竞价的业务逻辑：JavaScript 代码，用于考虑每个出价的价格和元数据，并计算“理想程度”得分。具有最高理想度得分的出价将赢得竞价。
卖家会针对竞价结果生成报告，其中包括有关清算价格和任何其他付款的信息。胜出的买方和未胜出的买方也可以自行生成报告。

本文档将介绍如何配置和启动设备端竞价。

配置 Protected Audience API 广告竞价

如需运行 Protected Audience API 广告竞价，第一步是配置竞价。为此，您需要创建一个 auctionConfig 对象。以下是此类配置的一个示例：

const auctionConfig = {
  seller: 'https://seller.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://buyer-1.example', 'https://buyer-2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://buyer-1.example': {...},
    'https://buyer-2.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://buyer-1.example': 50,
    'https://buyer-2.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://component-seller.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ],
  resolveToConfig: [true|false],
};

`AuctionConfig`属性

必要属性

auctionConfigs 唯一必需的属性是 seller、decisionLogicUrl 和 interestGroupBuyers。

属性	示例	角色
seller	https://seller.example	卖家的来源。
decisionLogicUrl	https://seller.example/decision-logic.js	用于竞价 JavaScript 决策逻辑工作程序的网址。此字段需要与卖方字段具有相同的来源。
interestGroupBuyers	[https://buyer-1.example, https://buyer-2.example, ...]	被要求参与竞价的所有兴趣群体所有者的来源

可选属性

auctionConfigs 的其余属性是可选的。

属性	示例	角色
trustedScoringSignalsUrl	https://seller.example/scoring-signals	卖方的键值对服务器的网址。在广告评分过程中，系统会使用广告素材的呈现网址作为键来查询此数据。此字段需要与卖方字段具有相同的来源。
auctionSignals	{"category":"news"}	JSON 可序列化对象，表示参与竞价的所有买方和卖方可用的信号。
sellerSignals	{...}	JSON 可序列化对象，表示仅供卖方使用的信号。
perBuyerSignals	{https://dsp.example: {...}, https://another-buyer.example: {...}, ... }	可供特定买方使用的信号。信号可以来自卖家，也可以来自买家本人。
perBuyerTimeouts	{https://www.example-dsp.com: 50, https://www.another-buyer.com: 200, *: 150, ...},	特定买方的 generateBid() 脚本的最长运行时长（以毫秒为单位）。通配符符号将应用于未定义特定超时时限的每个买家。
sellerTimeout	100	卖方 scoreAd() 脚本的最长运行时长（以毫秒为单位）。
componentAuctions	[{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...]	针对组件竞价的其他配置。
resolveToConfig	true\|false	一个布尔值，用于指示 runAdAuction() 返回的 promise 在为 true 时解析为 FencedFrameConfig（用于 <fencedframe> 中），在为 false 时解析为不透明的 urn:uuid 网址（用于 <iframe> 中）。默认值为 false。

异步提供信号

某些信号（由 auctionSignals、sellerSignals、perBuyerSignals 和 perBuyerTimeouts 字段配置的信号）的值可以选择性地不以具体值的形式提供，而是以 Promise 的形式提供。这样一来，竞价的某些部分（例如加载脚本和可信信号，以及启动隔离的工作程序）就可以与这些值的计算（或网络检索）重叠。工作程序脚本只会看到已解析的值；如果任何此类 Promise 被拒绝，除非竞价已失败或以其他方式中止，否则竞价将中止。

配置包含多个卖家的竞价

在某些情况下，多个卖家可能希望参与竞价，而单独竞价的胜出者会被传递给由另一卖家进行的另一场竞价。这些传递的单独竞价称为组件竞价。为了促成这些组件竞价，componentAuctions 对象可以包含每个卖方组件竞价的其他竞价配置。每个组成部分竞价的胜出出价将传递给“顶级”竞价，后者将最终确定竞价结果。组成部分竞价的 auctionConfig 可能没有自己的 componentAuctions。如果 componentAuctions 不为空，则 interestGroupBuyers 必须为空。也就是说，对于任何特定的 Protected Audience 竞价，要么只有一个卖方且没有组件竞价，要么所有出价都来自组件竞价，并且顶级竞价只能从组件竞价的胜出者中进行选择。

开展竞价

卖家通过调用 navigator.runAdAuction() 向用户的浏览器发出开始广告竞价的请求。

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

runAdAuction() 调用会返回一个解析为广告的 Promise。发布商网页上的任何代码都无法通过 runAdAuction() 的结果检查胜出的广告或以其他方式了解其内容。如果在 AuctionConfig 中将 resolveToConfig 标志设置为 true，则返回的 FencedFrameConfig 对象只能在围栏框架中呈现。如果该标志设置为 false，则返回可在 iframe 中呈现的不透明 URN。runAdAuction 可能会返回 null 值，表示未选择任何广告。在这种情况下，卖方可能会选择展示内容相关广告。