以買方身分整合 B&A

出價和競價 (B&A) 服務是一組服務,適用於在可信執行環境 (TEE) 中運作的廣告買方和賣方,可協助進行 Protected Audience (PA) 競價。本開發人員指南說明買方如何整合 Chrome 的 B&A PA 競價。

總覽

如要透過 B&A 服務參與 Protected Audience 競價,買方必須更新興趣群組 (IG),以便最佳化酬載,縮短競價延遲時間。

買方必須執行下列酬載最佳化工作:

出價和競價的興趣群組

以下是 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 旗標略過這些值。您可以使用 K/V 服務提供省略的信號。
  • 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 物件。

如果未設定此旗標,興趣群組中定義的 userBiddingSignals 值就會在出價服務的 generateBid() 中提供。

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() 函式中,這些物件將無法使用。

為處理缺少的廣告資訊,買方會在興趣群組設定中維護與每則廣告相關聯的 ID (adRenderIdadComponentRenderId)。這個 ID 必須是長度不超過 12 個位元組的 DOMString。如果 ID 採用 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) 計算優先順序。買方可以覆寫賣方的優先順序信號。

屬性 說明
優先順序向量 買方會將向量做為 K/V 服務的 priorityVector 鍵值
優先信號 賣方會透過設定競價設定的 priority_signals 提供信號
優先信號覆寫 買方會在競價設定的 PerBuyerConfig priority_signals_overrides 欄位中提供覆寫值。

在競價期間,瀏覽器會計算 priorityVectorprioritySignals 中相符鍵的稀疏內積,以決定優先順序。在下圖中,優先順序的計算方式是 (4 * 2) + (3 * -1),而 (4 * 2) + (3 * -1) 會減為 8 + -3,因此這個興趣群組在競價時的優先順序為 5

優先順序向量和優先順序信號物件中的每個鍵都會相乘,然後將結果加總起來計算優先順序
圖 1:使用買方的向量和賣方的信號計算優先順序

您也可以使用其他信號,在 B&A 中設定優先順序:

Signal 說明
deviceSignals.one 這個值一律為 1,可用於在點積積中加入常數。
deviceSignals.ageInMinutes 這個值會以分鐘為單位,以 0 到 43,200 的整數表示興趣群組的加入時間 (自最近加入興趣群組以來的時間)。
deviceSignals.ageInMinutesMax60 這個值與 ageInMinutes 信號相同,但上限為 60。如果群組已超過 1 小時,則會傳回 60。
deviceSignals.ageInHoursMax24 這個值會以小時為單位,說明興趣群組的年齡,上限為 24 小時。如果群組已存在超過一天,則會傳回 24。
deviceSignals.ageInDaysMax30 這個值會以天數表示興趣群組的年齡,上限為 30 天。如果群組已超過 30 天,則會傳回 30。

詳情請參閱 GitHub 上的說明文件

設定受信任出價信號

由於 B&A 競價酬載會省略部分資料,您可以使用鍵/值服務,將省略的資料做為可信任的出價信號,提供給 generateBid() 函式。

K/V 服務可提供下列省略資料:

  • userBiddingSignals (如果由買方使用)
  • 與每則廣告相關聯的 metadata
  • 與每則廣告相關聯的 adRenderId
  • 報表 ID
興趣群組中省略的資料可傳送至買方的收集伺服器。收集伺服器會將資料推送至鍵/值服務,而瀏覽器會在稍後從鍵/值服務載入這些資料
圖 2:信任信號設定範例

其中一種做法是在受信任的出價信號鍵中加入專屬 ID,然後將相關聯的資料傳送至伺服器,以便載入至 Key/Value Service。不過,實際實作方式取決於廣告技術,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 定義專屬 ID,並將該 ID 納入信號金鑰。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() 傳回算繪網址

由於 ads 物件已從 B&A 競價酬載中省略,因此必須重新建立從 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
  ]
})

接著,我們會傳送使用者偏好的顏色和產品資訊,並將其載入至 Key/Value Service:

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 競價酬載中,因此 ID 會透過可信的出價信號傳送至 generateBid()。確定要使用的報表 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 會透過 reportWin()buyerReportingSignals 中提供:

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

如果 generateBid() 未傳回 buyerReportingId,則 interestGroupName 值會在 buyerReportingSignals 中顯示,而非 buyerReportingId

詳情請參閱報表 ID 指南

後續步驟

您可以參考下列資源

瞭解詳情

有任何問題嗎?