通过单个卖方进行基于浏览器的竞价

本文档将简要介绍如何使用单个卖方的 Protected Audience 数据（在 Protected Audience API 的当前迭代中使用）开展竞价。单个卖方的竞价可以作为涉及多个卖方的更复杂的竞价的一部分执行。在这种情况下，单卖方竞价称为“组件竞价”，它可以为有多个卖方参与的“顶级竞价”提供候选广告。

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

Protected Audience API 广告竞价的六个阶段

Protected Audience API 广告竞价的六个阶段
此图展示了 Protected Audience API 广告竞价的各个阶段。
  1. 某位用户访问某个展示广告的网站。
  2. 卖方的代码执行 navigator.runAdAuction()。这指定了要销售的广告空间以及谁可以出价。卖方还必须包含一个用于为每个出价评分的脚本 scoreAd()。
  3. 系统会执行受邀买方的代码，以生成出价、相关广告素材的网址和其他数据。出价脚本可以从买方的键值对服务查询实时数据，例如剩余的广告系列预算。
  4. 卖方的代码会对每个出价进行评分并选择胜出者。此逻辑使用出价金额和其他数据来返回出价的期望值。无法击败内容相关定位胜出者的广告将会被拒绝。卖方可以使用自己的键值对服务来处理实时数据。
  5. 胜出的广告以不透明值形式返回，该值显示在围栏帧中。卖方和发布商都将无法查看此值。
  6. 系统将向卖方和胜出的买方报告竞价。

当用户前往展示广告的页面时，就可能会发生竞价。竞价可以提前进行，以便在广告位显示时广告素材准备就绪。

卖方发起广告竞价、使用作为 scoreAd() 函数提供的自定义逻辑为候选广告评分，并负责向自己和胜出的买方报告竞价结果。卖方还可以执行发布商规则并使用其 scoreAd() 函数过滤广告质量。

卖方可以参考：

  • 依靠自身在网站上托管广告内容的内容发布商
  • 供应方平台 (SSP)，与广告发布商合作并提供其他服务
  • 第三方脚本，可帮助发布商参与广告竞价。

开展竞价的前提条件

卖方需要定义两个 JavaScript 函数才能开展竞价：

  • scoreAd()：为候选广告评分
  • reportResult()：负责向卖方自行报告竞价结果

这些脚本需要从卖方拥有的单个端点传送。

scoreAd()

卖方需要定义一个由其拥有的端点提供的 scoreAd() 函数。该端点在竞价配置中指定为 decisionLogicUrl。scoreAd() 函数具有以下签名：

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

scoreAd() 形参如下：

  • adMetaData，它是买方提供的广告素材的任意元数据。这是一个 JSON 可序列化对象，卖方和买方需要定义并同意结构。
  • bid：表示出价的数值。
  • auctionConfig：用于执行竞价的竞价配置。
  • trustedScoringSignals：这是竞价时从卖方的键值对服务器读取的信号。平台会将候选广告的 renderUrl 用作此查找的键。
  • browserSignals：由浏览器构建的对象，包含浏览器知道的信息以及卖方的竞价脚本可能想要验证的信息。
  • directFromSellerSignals 是可能包含以下字段的对象： ** sellerSignals：与 auctionConfig.sellerSignals 类似，但使用 directFromSellerSignals 机制传递。 ** auctionSignals：与 auctionConfig.auctionSignals 类似，但使用 directFromSellerSignals 机制传递。

以下是 browserSignals 的示例。请注意，候选广告的 renderUrl 可通过以下信号获取：

{ 'topWindowHostname': 'www.example-publisher.com',
  'interestGroupOwner': 'https://www.example-buyer.com',
  'renderURL': 'https://cdn.com/render_url_of_bid',
  'renderSize': {width: 100, height: 200}, /* if specified in the bid */
  'adComponents': ['https://cdn.com/ad_component_of_bid',
                   'https://cdn.com/next_ad_component_of_bid',
                   ...],
  'biddingDurationMsec': 12,
  'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
  'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}

reportResult()

卖方需要定义一个从他们拥有的端点传送的 reportResult() 函数。该端点在竞价配置中指定为 decisionLogicUrl。reportResult() 函数具有以下签名：

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

reportResult() 形参如下：

  • auctionConfig：用于执行竞价的竞价配置。
  • browserSignals：由浏览器构建的对象，包含浏览器知道的信息以及卖方的竞价脚本可能想要验证的信息。这是传递给 scoreAds() 函数的同一对象。

reportResult() 会返回 signalsForWinner，后者是传递给胜出买方的报告函数的任意 JSON 对象。其中应包括卖方可以提供的所有与竞价相关的信息（买方在生成报告时要求提供此类信息）。

进行 Protected Audience API 竞价

要开展竞价，卖方必须完成四个主要步骤。请注意，这些步骤假定卖方已设置端点，以返回本指南前面提到的必需 JavaScript。

  1. 配置竞价。此步骤包括创建 auctionConfig 对象。这样一来，卖方就可以指定哪个买方应参与竞价，并提供在出价生成或广告评分期间可能相关的任何信号。
  2. 通过调用 navigator.runAdAuction() 并传入在上一步中创建的配置来执行竞价。这会启动一系列买方，包括出价和评分。此步骤的最终结果是可以呈现以展示广告的候选广告。
  3. 在围栏框架或 iframe 中呈现胜出的广告。
  4. 报告竞价结果。有一个函数 navigator.sendReportTo() 将启动报告。卖方始终会收到竞价结果报告。只有赢得竞价的买方才会收到报告。这会使用本指南前面部分介绍的卖方的 reportResult() 向其服务器报告。