在浏览器中开展仅包含单个卖家的竞价

本文档简要介绍了如何使用 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() 向其服务器报告。