本頁面由 Cloud Translation API 翻譯而成。

以買方身分整合 B&A

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

總覽

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

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

joinAdInterestGroup() 工作
generateBid() 工作

出價和競價的興趣群組

以下是 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` 標記
`ads` 和 `adComponents` 中的 `adRenderId`	二手	未使用	如果已設定 `omit-ads` 旗標，`ads` 中的 `adRenderId` 只會出現在酬載的 `browserSignals.prevWins` 中。`adComponents` 中定義的 `adRenderId` 不會包含在酬載中。如果未設定 `omit-ads` 旗標，可在 `browserSignals.prevWins`、`interestGroup.adRenderIds` 和 `interestGroup.adComponentRenderIds` 中使用。
`ads` 和 `adComponents` 中的 `renderURL`	二手	二手	否
`ads` 和 `adComponents` 中的 `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 標記會指示瀏覽器略過競價酬載中的 ads 和 adComponents 物件。

adRenderId 會顯示在 browserSignals 的 prevWins 屬性中。

如果未設定標記，generateBid() 的 interestGroup 引數中 adRenderIds 和 adComponentRenderIds 欄位就會包含對應的廣告轉譯 ID。

我們強烈建議買方選擇 omit-ads 標記。日後，為了進一步最佳化酬載，我們可能會淘汰從用戶端傳遞轉譯 ID 和廣告元件轉譯 ID 的做法。

系統會透過在 trustedBiddingSignals 中提供相關資訊，處理省略的資料。您可以個別使用這些旗標，不必同時使用。

使用範例：

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

設定廣告轉譯 ID

為縮減 B&A 競價酬載的大小，系統會省略興趣群組的 ads 和 adComponents 物件，因此在出價服務中執行的 generateBid() 函式中，這些物件將無法使用。

為處理缺少的廣告資訊，買方會在興趣群組設定中維護與每則廣告相關聯的 ID (adRenderId 和 adComponentRenderId)。這個 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` 欄位中提供覆寫值。

在競價期間，瀏覽器會計算 priorityVector 和 prioritySignals 中相符鍵的稀疏內積，以決定優先順序。在下圖中，優先順序的計算方式是 (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() 傳回的轉譯網址。重建轉譯網址的方式取決於您的導入方式，且傳回的網址必須與興趣群組中定義的轉譯網址相符。

您可以採用的一種方法是保留基本網址，並使用 interestGroup 和 trustedBiddingSignals 中的資訊填入範本。

在本範例中，我們會根據顏色和產品定義 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 指南。

後續步驟

您可以參考下列資源

瞭解詳情

進一步瞭解 Chrome 中的 B&A 競價設定
按照端對端本機測試程式碼研究室中的步驟，使用 B&A 實驗 Protected Audience。

有任何問題嗎？

如果您對出價與競價服務有任何疑問，請在 B&A Services 存放區中提出問題。
如果您對 Privacy Sandbox 有任何疑問，請在 privacy-sandbox-dev-support 存放區中提出問題。