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

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