以买方的身份与 B&A 集成

出价和竞价 (B&A) 服务是一组面向广告买方和卖方的服务,这些服务在可信执行环境 (TEE) 中运行,以便进行 Protected Audience (PA) 竞价。本开发者指南介绍了买方如何与 Chrome 的 B&A PA 竞价集成。

概览

如需使用 B&A 服务参与 Protected Audience 竞价,买方需要更新兴趣群体 (IG) 以优化载荷,从而缩短竞价延迟时间。

买方要求执行以下载荷优化任务:

针对 B&A 的兴趣群体

以下是已应用载荷优化的 B&A PA 竞价的兴趣群体配置示例:

navigator.joinAdInterestGroup({
  name: 'example-ig',
  owner: 'https://dsp.example',

  // An ID is mapped to each render URL
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max,
      buyerReportingId: 'brid123', // Optional
      buyerAndSellerReportingId: 'bsrid123', // Optional
      selectableBuyerAndSellerReportingId: ['sbsrid123', 'sbsrid456'], // Optional
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adRenderId: 'abcdefgh'
    },
  ],

  // Flags are set to omit data in the B&A auction payload
  auctionServerRequestFlags: ['omit-ads', 'omit-user-bidding-signals'],

  // Data not included in the B&A auction payload can be fetched as trusted signals
  // The following is an example of how the keys could look, but the actual
  // implementation is up to the ad tech
  trustedBiddingSignalsKeys: [
    'exampleUserBiddingSignalsKey',
    'exampleAdRenderIdKey',
    'exampleAdMetadataKey',
    'exampleAdReportingIdKey',
  ],

  // Optionally, interest groups can be prioritized
  priority: 0.0,
});

B&A 和设备端兴趣群体配置之间的区别如下:

字段 B&A IG 设备端 IG 包含在 B&A 竞价载荷中
auctionServerRequestFlags 已使用 未使用
userBiddingSignals 不推荐 已使用 否,如果设置了 omit-user-bidding-signals 标志
adsadComponents 中的 adRenderId 已使用 未使用 如果设置了 omit-ads 标志,ads 中的 adRenderId 仅在载荷的 browserSignals.prevWins 中可用。载荷中未包含 adComponents 中定义的 adRenderId

如果未设置 omit-ads 标志,则在 browserSignals.prevWinsinterestGroup.adRenderIdsinterestGroup.adComponentRenderIds 中可用。

adsadComponents 中的 renderURL 已使用 已使用
adsadComponents 中的 metadata 未使用 已使用
ads 中的报告 ID 已使用 已使用
  • auctionServerRequestFlags 字段允许设置标志,以指示浏览器忽略 B&A 竞价载荷中的某些数据。
  • 您可以在兴趣群体中定义 userBiddingSignals 值,但建议使用 omit-user-bidding-signals 标志忽略这些值。您可以使用键值对服务提供省略的信号。
  • adRenderId 字段会随关联的 renderURL 一起设置,但只有 adRenderId 会成为 B&A 竞价载荷的一部分。在竞价期间稍后从 generateBid() 返回的呈现网址必须与 IG 中定义的呈现网址一致。
  • 报告 ID 在 B&A IG 中定义,但不包含在 B&A 竞价载荷中。在竞价期间稍后从 generateBid() 返回的报告 ID 必须与 IG 中定义的呈现网址一致。
  • ad.metadata 和报告 ID 不包含在 B&A 竞价载荷中,而是通过可信键值对服务使用情况提供。

请注意,ads 中的 renderURL 和报告 ID 仍在兴趣群组配置中定义,但不会包含在竞价请求载荷中,因为浏览器会检查从出价服务的 generateBid() 函数返回的呈现网址和报告 ID 是否与兴趣群组中定义的值相匹配。

joinAdInterestGroup() 项任务

需要针对 joinAdInterestGroup() 调用执行以下任务。

设置服务器请求标志

joinAdInterestGroup() 配置的 auctionServerRequestFlags 字段接受以下标志:

标志 说明
omit-user-bidding-signals omit-user-bidding-signals 标志会忽略竞价载荷中的 userBiddingSignals 对象。

如果未设置此标志,则在出价服务的 generateBid() 中将会显示在兴趣群体中定义的 userBiddingSignals 值。

omit-ads omit-ads 标志会指示浏览器忽略竞价载荷中的 adsadComponents 对象。

adRenderId 将在 browserSignalsprevWins 属性中提供。

如果未设置此标志,则 generateBid()interestGroup 参数中的 adRenderIdsadComponentRenderIds 字段将包含相应的广告呈现 ID。

强烈建议买方选择 omit-ads 标志。未来某个时候,我们可能会弃用从客户端传递呈现 ID 和广告组件呈现 ID 的做法,以进一步优化载荷。

系统会通过在 trustedBiddingSignals 中提供相关信息来处理省略的数据。这些标志可以单独使用,也可以组合使用。

用法示例:

navigator.joinAdInterestGroup({
  auctionServerRequestFlags: ['omit-user-bidding-signals', 'omit-ads'],
});

设置广告呈现 ID

为了减小 B&A 竞价载荷的大小,系统会省略兴趣群组的 adsadComponents 对象,因此这些对象在出价服务中运行的 generateBid() 函数内不可用。

为了处理缺失的广告信息,买方会维护与兴趣群体配置中的每个广告关联的标识符 (adRenderIdadComponentRenderId)。标识符必须是长度不超过 12 个字节的 DOMString。如果标识符采用 Base64 编码,则其长度不得超过 12 字节。

包含广告呈现 ID 的兴趣群体示例:

navigator.joinAdInterestGroup({
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adComponentRenderId: 'abcdefgh'
    },
  ],
});

与广告关联的 adRenderId 会在 generateBid()prevWins.browserSignals 中显示。

虽然请求载荷中不包含 renderURL,但 generateBid() 返回的呈现网址必须与兴趣群体配置中定义的呈现网址一致。广告技术平台可以在 trustedBiddingSignals 中发回广告元数据和其他信息,以便在 generateBid() 执行期间为出价生成广告呈现网址和广告组件呈现网址。

设置兴趣群体优先级

Chrome 允许买方对兴趣群组进行排序。如果达到卖方设置的每个买方载荷大小限制,则在为卖方生成 B&A 竞价载荷时,系统会使用兴趣群体优先级值来移除单个买方的优先级较低的兴趣群体。在不同买家之间选择兴趣群体时,浏览器会根据序列化载荷的大小进行决策。默认情况下,每个买家的规模都是相同的。请注意,实际的优先级设置是在 B&A 服务器上进行的,而不是在生成请求载荷时进行的。

系统会在竞价时使用买方的优先级矢量 (priorityVector) 和卖方的优先级信号 (prioritySignals) 计算优先级。买方可以替换卖方的优先级信号。

属性 说明
优先级矢量 买方将矢量作为键值对服务中的 priorityVector 键的值提供
优先信号 卖方通过设置竞价配置的 priority_signals 来提供信号
优先信号替换项 买方在竞价配置的 PerBuyerConfigpriority_signals_overrides 字段中提供替换项。

在竞价期间,浏览器会计算 priorityVectorprioritySignals 中匹配键的稀疏点积,以确定优先级。在下图中,优先级由 (4 * 2) + (3 * -1) 计算得出,该值会缩减为 8 + -3,因此此兴趣群组在竞价时的优先级为 5

优先级矢量和优先级信号对象中的每个键都会相互相乘,然后将结果相加以计算优先级
图 1:使用买方的矢量和卖方的信号计算优先级

您还可以使用其他信号在 B&A 中确定优先顺序:

信号 说明
deviceSignals.one 该值始终为 1,可用于向点积添加常量。
deviceSignals.ageInMinutes 此值描述了兴趣群体的年龄(自最近一次加入兴趣群体以来的时间),以介于 0 到 43,200 之间的整数表示。
deviceSignals.ageInMinutesMax60 该值的描述与 ageInMinutes 信号相同,但上限为 60。如果组已存在超过 1 小时,则返回 60。
deviceSignals.ageInHoursMax24 此值描述兴趣群体的时长(以小时为单位),上限为 24 小时。如果组已超过 1 天,则返回 24。
deviceSignals.ageInDaysMax30 此值描述了兴趣群组的年龄(以天为单位),上限为 30 天。如果组已超过 30 天,则返回 30。

如需了解详情,请参阅 GitHub 上的说明文档

设置可信出价信号

由于 B&A 竞价载荷中会省略一些数据,因此您可以使用键值对服务将省略的数据作为可信出价信号提供给 generateBid() 函数。

K/V 服务可以提供以下省略的数据:

  • userBiddingSignals(如果由买方使用)
  • 与每个广告关联的 metadata
  • 与每个广告关联的 adRenderId
  • 报告 ID
兴趣群组中被省略的数据可以发送到买方的收集服务器。集合服务器会将数据推送到键值对服务,稍后,浏览器会从键值对服务加载这些数据
图 2:可信信号设置示例

一种方法是在可信出价信号键中添加唯一标识符,然后将关联的数据发送到您的服务器,以便将其加载到键值对服务中。不过,实际实现取决于广告技术平台,API 并非强制性规定。

以下示例介绍了一种可实现的方法:

const ad1RenderURL = 'https://dsp.example/ad-1.html';
const ad2RenderURL = 'https://dsp.example/ad-2.html';
const ad1RenderId = 'render-id-1';
const ad2RenderId = 'render-id-2';
const ad1ReportingId = 'reporting-id-1';
const ad2ReportingId = 'reporting-id-2';

// Generate a unique identifier
const id = crypto.randomUUID();

// Define the keys with the unique ID
const trustedSignalsKeyForIG = `interest-group-${id}`

// Set the keys in the interest group
navigator.joinAdInterestGroup({
  // …
  ads: [
    {
      renderURL: ad1RenderURL,
      adRenderId: ad1RenderId,
      buyerReportingId: ad1ReportingId
    },
    {
      renderURL: ad2RenderURL,
      adRenderId: ad2RenderId,
      buyerReportingId: ad2ReportingId
    },
  ],
  trustedBiddingSignalsKeys: [
    trustedSignalsKeyForIG
  ]
});

// Send the associated data to your server to be loaded into the Key/Value Service
fetch('https://dsp.example/kv/load', {
  method: 'POST',
  body: JSON.stringify({
    id,
    [trustedSignalsKeyForIG]: {
      userBiddingSignals: {
        favoriteColor: 'blue'
      },
      ads: [
        {
          renderURL: ad1RenderURL,
          adRenderId: ad1RenderId,
          buyerReportingId: ad1ReportingId,
          metadata: {
            color: 'red'
          }   
        },
        {
          renderURL: ad2RenderURL,
          adRenderId: ad2RenderId,
          buyerReportingId: ad2ReportingId,
          metadata: {
            color: 'blue'
          }   
        },
      ]
    }
  })
});

在此示例中,为 IG 定义了一个唯一标识符,该标识符会成为可信信号键的一部分。IG 的键及其关联的值会发送到您的服务器,以加载到键值对服务中。在竞价期间的稍后时间,浏览器会提取可信信号,并将其提供给买方的 generateBid() 函数。

根据需要从 K/V 返回兴趣群体更新信号

可信信号的 updateIfOlderThanMs 键用于在通常的每日间隔时间之前更新兴趣群体。如果兴趣群组在超过为 updateIfOlderThanMs 键返回的毫秒值的时间段内未加入或更新,系统将使用 updateURL 机制更新该兴趣群组。请注意,Chrome 不会超过每 10 分钟一次的频率更新兴趣群组。

如果 B&A 竞价返回的胜出广告与存储在浏览器中的兴趣群体中定义的广告不匹配,则浏览器将在竞价中失败。updateIfOlderThanMs 机制有助于确保浏览器和 B&A 竞价对兴趣群体中的广告组达成一致。

如需了解详情,请参阅说明文档

generateBid() 项任务

需要针对 generateBid() 调用执行以下任务。

读取浏览器信号

传入 B&A generateBid() 调用的 browserSignals 对象如下所示:

{
  topWindowHostname: 'advertiser.example',
  seller: 'https://ssp.example',
  topLevelSeller: 'https://ssp-top.example',
  joinCount: 5,
  bidCount: 24,
  recency: 1684134092,

  // prevWins is [timeInSeconds, adRenderId]
  prevWins: [
    [9342, 'render-id-1'],
    [1314521, 'render-id-2']
  ],

  // Compiled WebAssembly code
  wasmHelper: WebAssembly.Module

  // Data-Version value from K/V response, if available
  dataVersion: 1,
}

browserSignals 中提供以下经过修改或新增的属性:

属性 说明
prevWins prevWins 是一个包含时间和广告的元组数组。时间表示自关联广告在过去 30 天内上次胜出以来经过的秒数。

它已修改为提供 adRenderId 而非 ad 对象。

wasmHelper biddingWasmHelperURL 提供的代码的已编译对象。
dataVersion 可信服务器可以选择包含在 generateBid() 中可用的数值 Data-Version 响应标头。

如需了解详情,请参阅 GitHub 上的说明文档

generateBid() 返回呈现网址

由于 B&A 竞价载荷中省略了 ads 对象,因此必须重新创建从 generateBid() 返回的呈现网址。如何重新创建呈现网址取决于您的实现,并且返回的网址必须与兴趣群体中定义的呈现网址一致。

一种可行的方法是维护一个基本网址,并使用 interestGrouptrustedBiddingSignals 中的信息填充模板。

在此示例中,我们将根据颜色和商品定义 4 个广告:

await navigator.joinAdInterestGroup({
  ads: [
    { renderURL: 'https://dsp.example/red-shirt-ad.html', adRenderId: 'arid1'},
    { renderURL: 'https://dsp.example/blue-shirt-ad.html', adRenderId: 'arid2'},
    { renderURL: 'https://dsp.example/red-pants-ad.html', adRenderId: 'arid3'},
    { renderURL: 'https://dsp.example/blue-pants-ad.html', adRenderId: 'arid4'},
  ],
  trustedBiddingSignalKeys: [
    'userBiddingSignals-someUniqueId',
    // ...and more
  ]
})

然后,我们会发送用户的喜爱颜色和商品信息,以便加载到键值对服务中:

fetch('https://dsp.example/kv/load', {
  body: JSON.stringify({
    'userBiddingSignals-someUniqueId': {
      favoriteColor: 'blue',
      favoriteProduct: 'shirt'
    }
  })
})

稍后,当竞价运行时,可信出价信号会在 generateBid() 中提供,并且这些信息可用于重构网址:

function generateBid(..., trustedBiddingSignals, browserSignals) {
  const { userBiddingSignals } = trustedBiddingSignals
  const { favoriteColor, favoriteProduct } = userBiddingSignals

  return {
    bid: 1,
    render: `https://dsp.example/${favoriteColor}-${favoriteProduct}-ad.html`
  }
}

generateBid() 返回报告 ID

由于报告 ID 不包含在 B&A 竞价载荷中,因此 generateBid() 可以通过可信出价信号获取该 ID。确定要使用的报告 ID 后,generateBid() 会返回所选的报告 ID。返回的 ID 必须与兴趣群组中定义的 ID 一致。

在此示例中,系统选择了广告 1,并从 generateBid() 返回了其关联的呈现 ID:

generateBid(..., trustedBiddingSignals, ) {
  const { ad1ReportingId, ad2reportingId } = trustedBiddingSignals;
  // ...
  return {
    bid: 1,
    render: 'https://dsp.example/ad-1.html'
    buyerReportingId: ad1reportingId
  }
}

返回的报告 ID 会通过 buyerReportingSignalsreportWin() 中提供:

reportWin(..., buyerReportingSignals) {
  const { buyerReportingId } = buyerReportingSignals;
}

如果 generateBid() 未返回 buyerReportingId,则 buyerReportingSignals 中会提供 interestGroupName 值,而不是 buyerReportingId

如需了解详情,请参阅报告 ID 指南

后续步骤

您可以使用以下资源

了解详情

有疑问?