瞭解如何設定 Protected Audience API 競價。
賣方進行的裝置端競價
我們會在銷售廣告空間的網站上執行裝置端 Protected Audience 競價，我們稱之為賣方進行競價的一方。許多方都可能擔任賣方：網站可能會自行執行廣告競價，或加入第三方指令碼來執行競價，或採用結合執行裝置端競價與其他伺服器端廣告競價活動的賣方平台。賣方在裝置端廣告競價中有三項基本工作：
- 賣方可以決定 (a) 哪些買方可能參與，以及 (b) 這些買方興趣群組的出價符合參與競價的資格。如此一來，賣方就能強制執行網站規則，指定允許在網頁上顯示的廣告。
- 賣方負責競價的商業邏輯：JavaScript 程式碼會考量每個出價的價格和中繼資料，並計算「合適度」分數。理想性分數最高的出價將贏得競價。
- 賣方執行競價結果報表，包括價格和其他報酬的相關資訊。得標和流失的買家也可以製作自己的報表
本文件說明如何設定及啟動裝置端競價。
設定 Protected Audience API 廣告競價
如要執行 Protected Audience API 廣告競價，第一步是設定競價。方法是建立 auctionConfig 物件。以下是這類設定的範例：
const auctionConfig = {
seller: 'https://seller.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://buyer-1.example', 'https://buyer-2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://buyer-1.example': {...},
'https://buyer-2.example': {...},
...
},
perBuyerTimeouts: {
'https://buyer-1.example': 50,
'https://buyer-2.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://component-seller.example',
'decisionLogicUrl': ...,
...
},
...
],
resolveToConfig: [true|false],
};
AuctionConfig 項資源
必要屬性
auctionConfigs 唯一的必要屬性是 seller、decisionLogicUrl 和 interestGroupBuyers。
| 屬性 | 範例 | 角色 |
|---|---|---|
| seller | https://seller.example | 賣方的來源。 |
| decisionLogicUrl | https://seller.example/decision-logic.js | 競價 JavaScript 決策邏輯工作的網址。這個欄位必須與賣方欄位的來源相同。 |
| interestGroupBuyers | [https://buyer-1.example, https://buyer-2.example, ...] |
要求在競價中出價的所有興趣群組擁有者的來源 |
選用屬性
auctionConfigs 的其餘屬性為選用屬性。
| 屬性 | 範例 | 角色 |
|---|---|---|
| trustedScoringSignalsUrl | https://seller.example/scoring-signals | 賣家鍵/值伺服器的網址。在廣告評分過程中，系統會使用廣告素材的顯示網址做為鍵來查詢這項資訊。這個欄位必須與賣方欄位的來源相同。 |
| auctionSignals | {"category":"news"} | JSON 序列化物件，代表參與競價的所有買方和賣方可用的信號。 |
| sellerSignals | {...} | JSON 序列化物件，代表只有賣方可用的信號。 |
| perBuyerSignals | {https://dsp.example: {...}, https://another-buyer.example: {...}, ... } |
特定買方可用的信號。信號可能來自賣方，也可以是買方本身。 |
| perBuyerTimeouts | {https://www.example-dsp.com: 50, https://www.another-buyer.com: 200, *: 150, ...}, |
特定買家的 generateBid() 指令碼執行階段上限 (以毫秒為單位)。凡是未定義特定逾時的買方，都會套用萬用字元。 |
| sellerTimeout | 100 | 賣方 ScoreAd() 指令碼的執行階段長度上限 (毫秒)。 |
| componentAuctions | [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] | 元件競價的其他設定。 |
| resolveToConfig | 是|否 | 布林值，將 runAdAuction() 傳回的承諾解析為 FencedFrameConfig 在為 true (在 <fencedframe> 中使用) 時，設為不透明的 urn:uuid 網址；如果為 false (用於 <iframe> 中使用)。預設值為 false。 |
非同步提供信號
您可以選擇以 Promise 的形式提供某些信號的值 (由 auctionSignals、sellerSignals、perBuyerSignals 和 perBuyerTimeouts 欄位設定的值)，而非具體值。這樣可讓競價的某些部分 (例如載入指令碼和受信任信號，以及啟動隔離工作程式程序) 與這些值的運算 (或網路擷取) 重疊。工作小程式指令碼只會看到解析的值。如果任何此類 Promise 遭拒，競價就會取消，除非管理程序已經失敗或以其他方式取消。
設定由多個賣方參與的競價
在某些情況下，多個賣方可能會想參與競價，讓其他競價的勝出者傳遞至另一個競價，由其他賣方執行。這些在競價中傳遞的競價稱為元件競價。為了協助這些元件的競價，componentAuctions 物件可包含每位賣方元件競價的其他競價設定。這些元件競價的得標出價將傳遞至「頂層」競價，以做出最終的競價決定。元件競價的 auctionConfig 不能有自己的 componentAuctions。如果 componentAuctions 非空白，interestGroupBuyers 必須留空。也就是說，對於任何特定的 Protected Audience 競價，可能是單一賣方且沒有任何元件競價；或者所有出價都來自元件競價，頂層競價只能從元件競價中選出勝出者。
執行競價
賣方呼叫 navigator.runAdAuction()，向使用者的瀏覽器發出廣告競價邀請。
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
runAdAuction() 呼叫會傳回 Promise，這個要解析至廣告。發布商頁面上的任何程式碼皆無法檢查勝出的廣告，或從 runAdAuction() 結果瞭解其內容。如果 AuctionConfig 中的 resolveToConfig 標記設為 true，會傳回 FencedFrameConfig 物件，而該物件只能在圍欄頁框中轉譯。如果旗標設為 False，系統會傳回不透明 URN，並在 iframe 中顯示。runAdAuction 有可能傳回空值，表示未選取任何廣告。在這種情況下，賣方可能會選擇顯示內容比對廣告。