此页面由 Cloud Translation API 翻译。

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

了解如何配置 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 决策逻辑 Worklet 的网址。此字段必须与卖方字段具有相同的来源。
interestGroupBuyers	[https://buyer-1.example, https://buyer-2.example, ...]	所有兴趣群体所有者被请求参与竞价的出处

可选属性

auctionConfigs 的其余属性是可选的。

媒体资源	示例	角色
trustedScoringSignalsUrl	https://seller.example/scoring-signals	卖方的键值对服务器的网址。系统将在广告评分过程中查询此值，并将广告素材的呈现网址用作键。此字段必须与卖方字段具有相同的来源。
auctionSignals	{"category":"新闻"}	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，则从 runAdAuction() 返回的 promise 解析为 FencedFrameConfig（用于 <fencedframe>），或指向不透明的 urn:uuid 网址（如果为 false）。默认值为 false。

异步提供信号

某些信号（由 auctionSignals、sellerSignals、perBuyerSignals 和 perBuyerTimeouts 字段配置的信号）的值可以选择不作为具体值提供，而是作为 promise 提供。这样一来，竞价的某些部分（例如加载脚本和可信信号以及启动隔离的 Worklet 进程）可以与这些值的计算（或网络检索）重叠。Worklet 脚本只能看到已解析的值；如果任何此类 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 值，表示未选择任何广告。在这种情况下，卖方可能会选择展示内容相关广告。