此页面由 Cloud Translation API 翻译。

在竞价中出价以购买广告位

作为广告买方（DSP 和广告客户），您可能希望在发布商网站上参与 Protected Audience 广告竞价，以便将广告定位到您在广告客户网站上定义的兴趣群体。通过参与 Protected Audience 竞价，您能够以可保护隐私的方式在其他网站上触达已识别的客户。

在 Protected Audience 竞价中，您提供用于生成出价的逻辑，浏览器会使用该逻辑计算出价。这与其他直接提交出价（而非提供逻辑）的竞价架构不同。

您可以在 generateBid() JavaScript 函数中提供出价生成逻辑，并将该文件托管在您的服务器上。当您向兴趣组添加用户时，此文件的位置会作为 biddingLogicUrl 传递到兴趣组配置中。

在竞价期间，浏览器会提取 biddingLogicUrl 字段中指定的出价逻辑，并在安全的隔离环境中针对每个兴趣群体执行 generateBid() 函数，该环境与外部上下文的通信受到限制。当 generateBid() 执行时，浏览器会将信号作为实参传递给该函数。这些信号包含来自不同来源的各种信息，例如发布商的第一方数据、卖方的数据、实时数据等。您可以使用这些信号来计算出价，该值会通过 generateBid() 调用返回。提交出价后，浏览器将针对每个出价执行卖方的评分逻辑，以计算卖方的理想得分。

`generateBid()`

下文介绍了 generateBid() 函数的实参以及该函数返回的出价的结构：


generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals, directFromSellerSignals) {
  return {
    ad: adObject,
    adCost: optionalAdCost,
    bid: bidValue,
    bidCurrency: 'USD',
    render: {
      url: renderURL,
      width: renderWidth,
      height: renderHeight
    },
    adComponents: [
      {url: adComponent1, width: componentWidth1, height: componentHeight1},
      {url: adComponent2, width: componentWidth2, height: componentHeight2},
      // ...
    ],
    allowComponentAuction: false,
    modelingSignals: 123 // 0-4095 integer (12-bits)
  };
}

参数

generateBid() 接受以下参数：

参数	角色
`interestGroup`	广告买方传递的对象。兴趣组可能会通过 `dailyUpdateUrl` 进行更新。
`auctionSignals`	由卖方传递给 `navigator.runAdAuction()` 的竞价配置实参的属性。这会提供有关网页上下文（例如广告尺寸和发布商 ID）、竞价类型（最高出价竞价或次高价格竞价）和其他元数据的信息。
`perBuyerSignals`	由卖方传递的竞价配置实参的属性。如果卖方是 SSP，它会向买方服务器发出实时出价调用，并将响应通过管道传回；或者如果发布商网页直接与买方服务器联系，则可以从买方服务器提供有关网页的情境信号。如果是，买家可能需要检查 `generateBid()` 中这些信号的加密签名，以防范篡改。
`trustedBiddingSignals`	一个对象，其键是兴趣组的 `trustedBiddingSignalsKeys`，其值在 `trustedBiddingSignals` 请求中返回。
`browserSignals`	由浏览器构建的对象，可能包含有关网页上下文的信息（例如当前网页的 `hostname`，卖家可能会伪造此信息）以及兴趣组本身的数据（例如群组之前赢得竞价的记录，以便在设备上进行频次上限设置）。
`directFromSellerSignals`	来自特定卖家的信号，不同于 `auctionSignals` 和 `sellerSignals`，后者可以来自 `runAdAuction` 执行情境中的任何参与者。

浏览器信号

browserSignals 对象具有以下属性：

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  topLevelSeller: 'https://www.top-level-ssp.com',
  requestedSize: {width: 100, height: 200},  /* if specified in auction config */
  joinCount: 3,
  recency: 3600000,
  bidCount: 17,
  prevWinsMs: [[timeDeltaMs1,ad1],[timeDeltaMs2,ad2],...],
  wasmHelper: ...
  dataVersion: 1,
  adComponentsLimit: 40
}

属性	说明
`topWindowHostname`	发出 `runAdAuction()` 调用的主机名。
`seller`	出价提交到的卖方。在组件竞价中，此值为组件卖方。
`topLevelSeller`	组件竞价中的顶级卖方，仅在组件竞价中存在。
`requestedSize`	`requestedSize` 属性用于建议竞价的框架大小。卖方在竞价配置中设置请求的尺寸，并且该值在 `generateBid()` 中可供出价方使用。竞价中的出价方可能会为广告选择不同的内容尺寸，最终的尺寸将按比例缩放，以适应元素容器的尺寸。
`joinCount`	`joinCount` 字段表示相应设备在过去 30 天内加入相应兴趣组的次数，前提是相应兴趣组一直存储在设备上（也就是说，由于离开或会员资格到期，设备上存储的兴趣组没有出现间断）。
`recency`	`recency` 字段是指从相应设备加入相应兴趣组到现在的时长（以分钟为单位）
`bidCount`	兴趣组提交出价的次数。
`prevWinsMs`	`prevWinMs` 字段包含兴趣组的胜出广告，以及自上次胜出以来经过的时间（以毫秒为单位）。请注意，此处的广告对象仅包含 `renderURL` 和元数据字段。
`wasmHelper`	基于兴趣群组的 `biddingWasmHelperURL` 的 WebAssembly.Module 对象。
`dataVersion`	买方键/值服务响应中的 Data-Version 值。
`adComponentsLimit`	广告组件 `generateBid()` 可能返回的最大数量

计算出价

为了计算出出价值，generateBid() 中的代码可以使用函数形参的属性。

例如：

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
   //  ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    // ...
  }
}

返回出价

generateBid() 会返回一个包含以下属性的对象：

属性	角色
`ad`	有关广告的任意元数据，例如卖家希望了解的有关相应出价或广告素材的信息。卖方会在其竞价和决策逻辑中使用此信息。
`adCost`	一种数值，用于将报告广告客户的点击或转化费用从 generateBid 传递到 reportWin。此数字的精度限制为 8 位尾数和 8 位指数，任何舍入操作都是随机执行的。
`adComponents`	一个可选列表，最多包含 20 个组件，用于由多个部分组成的广告，取自传递给 `navigator.joinAdInterestGroup()` 的兴趣组实参的 adComponents 属性。
`allowComponentAuction`	一个布尔值，用于指示相应出价是否可用于组件竞价。如果未指定，则默认为“false”。
`bid`	将参与竞价的数值出价。卖方必须能够比较不同买方的出价，因此出价必须采用卖方选择的某种单位（例如“每千次展示的费用”）。如果出价为零或负数，则相应兴趣群体将根本不会参与卖方的竞价。借助此机制，买方可以针对广告的展示位置实施任何广告客户规则。
`bidCurrency`	出价所用的币种，用于检查币种。
`render`	一个字典，用于描述相应出价赢得竞价时应呈现的广告素材。其中包括： `url`：相应广告素材的网址。 `width`：广告素材的宽度。系统会将此尺寸与兴趣组中的声明进行匹配，并替换广告素材网址中存在的任何广告尺寸宏。当广告加载到受限框架中时，受限框架的内部框架（即广告素材可见的尺寸）将冻结为该尺寸，并且无法看到嵌入者对框架尺寸所做的更改。 `height`：广告素材的高度。有关详细说明，请参阅 `width`。
`modelingSignals`	传递给 `reportWin()` 的 0-4095 整数（12 位），带有噪声，如加噪和分桶方案中所述。无效值（例如负值、无限值和 `NaN` 值）将被忽略，不会传递。系统只会传递最低的 12 位。买方可以使用 `generateBid()` 函数中提供的信号（包括在创建兴趣群体时捕获的第一方买方数据中的数据 [`userBiddingSignals`]），推导出一个值，该值会传递给买方的胜出报告函数，以实现机器学习模型训练。