出價和競價 (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 不會包含在酬載中。如果未設定 |
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 物件。如果未設定此旗標,興趣群組中定義的 |
omit-ads |
omit-ads 標記會指示瀏覽器略過競價酬載中的 ads 和 adComponents 物件。
如果未設定標記, 我們強烈建議買方選擇 |
系統會透過在 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
。

您也可以使用其他信號,在 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

其中一種做法是在受信任的出價信號鍵中加入專屬 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 天內上次勝出後,已過的秒數。已修改為提供 |
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 存放區中提出問題 。