在本文件中,我們會概略介紹如何針對單一賣方使用 Protected Audience 資料執行競價 (在目前 Protected Audience API 疊代時使用的相同)。在較為複雜的競價涉及多個賣方的情況下,可以執行包含單一賣方的競價。在本例中,單一賣家競價稱為「元件競價」,可讓候選廣告參與有多個賣家參與的「頂層競價」。
請參閱開發人員指南,瞭解 Protected Audience API 的完整生命週期,以及 Protected Audience API 說明,深入瞭解賣方執行裝置端競價的方式。
Protected Audience API 廣告競價的六個階段
![Protected Audience API 廣告競價的六個階段](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/six-stages-a-protected-a-3e1dd6fdeddbe.png?authuser=7&hl=zh-tw)
- 使用者造訪顯示廣告的網站。
- 賣方的程式碼會執行
navigator.runAdAuction()
。這個欄位會指定要銷售和出價的對象。賣方也必須包含可為每項出價 (scoreAd()
) 評分的指令碼。 - 受邀買方的程式碼會執行出價、相關廣告素材的網址及其他資料。出價指令碼可查詢來自買家鍵/值服務的即時資料,例如剩餘廣告活動預算。
- 賣方程式碼會計算每個出價並選出勝出者。這個邏輯會使用出價值,其他資料則會傳回出價的理想結果。無法勝過內容相關勝出者的廣告會遭到拒絕。賣方可以使用自己的鍵/值服務處理即時資料。
- 勝出的廣告會以不透明值的形式傳回,該值會顯示在圍欄頁框中。賣方和發布商皆無法查看這個值。
- 系統會將競價回報給賣方和得標買方。
當使用者前往顯示廣告的網頁時,系統可能會舉行競價。 競價可能會提前執行,因此當廣告版位出現時,廣告素材就會處於就緒狀態。
賣方啟動廣告競價,使用自訂邏輯 (以 scoreAd()
函式提供的自訂邏輯) 為候選廣告評分,並負責向自己和得標買方回報競價結果。賣方也可以使用 scoreAd()
函式強制執行發布商規則,並篩選廣告品質。
賣家可參考以下資訊:
- 內容發布商,代替自己在網站上代管廣告素材
- 供應端平台 (SSP)、與廣告發布商合作並提供其他服務
- 第三方指令碼,協助發布商參與廣告競價。
執行競價的先決條件
賣方需要定義兩個 JavaScript 函式才能執行競價:
scoreAd()
,為候選廣告評分reportResult()
:負責向賣方本身回報競價結果
這些指令碼必須透過賣方擁有的單一端點提供。
scoreAd()
賣方必須定義 scoreAd()
函式,這個函式由自身擁有的端點提供。端點會在競價設定中指定為 decisionLogicUrl
。scoreAd()
函式具有下列簽章:
scoreAd(
adMetadata,
bid,
auctionConfig,
trustedScoringSignals,
browserSignals,
directFromSellerSignals)
scoreAd()
參數如下:
adMetaData
:買方提供的廣告素材相關任意中繼資料。這是一個 JSON 序列化物件,賣方和買方必須定義及同意結構。bid
,這是代表出價的數值。auctionConfig
,這是用來執行競價的競價設定。trustedScoringSignals
,這是從賣方的鍵/值伺服器讀取的信號。平台會使用候選廣告的renderUrl
做為這項查詢的索引鍵。browserSignals
是瀏覽器建構的物件,包含瀏覽器瞭解的資訊,以及賣方的競價指令碼可能需要驗證哪些資訊。directFromSellerSignals
是一個物件,可能包含下列欄位: **sellerSignals
:與auctionConfig.sellerSignals
類似,但會使用directFromSellerSignals
機制傳遞。 **auctionSignals
:類似auctionConfig.auctionSignals
,但會使用directFromSellerSignals
機制傳遞。
以下是 browserSignals
的範例。請注意,可透過下列信號取得候選廣告的 renderUrl
:
{ 'topWindowHostname': 'www.example-publisher.com',
'interestGroupOwner': 'https://www.example-buyer.com',
'renderURL': 'https://cdn.com/render_url_of_bid',
'renderSize': {width: 100, height: 200}, /* if specified in the bid */
'adComponents': ['https://cdn.com/ad_component_of_bid',
'https://cdn.com/next_ad_component_of_bid',
...],
'biddingDurationMsec': 12,
'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}
reportResult()
賣方需要定義 reportResult()
函式,這個函式可從自己擁有的端點提供。端點會在競價設定中指定為 decisionLogicUrl
。reportResult()
函式的簽名如下:
reportResult(auctionConfig, browserSignals) {
...
return signalsForWinner;
}
reportResult()
參數如下:
auctionConfig
,這是用來執行競價的競價設定。browserSignals
是瀏覽器建構的物件,包含瀏覽器瞭解的資訊,以及賣方的競價指令碼可能需要驗證哪些資訊。這與傳遞至scoreAds()
函式的物件相同。
reportResult()
會傳回 signalsForWinner
,這是傳送給得標買家報表函式的任意 JSON 物件。包括賣方可提供的所有競價相關資訊,而買方回報的競價要求應包含這些相關資訊。
執行 Protected Audience API 競價
賣方必須完成四個主要步驟才能舉行競價。請注意,這些步驟假設賣家已設定端點,可傳回本指南先前提及的必要 JavaScript。
- 設定競價。這個步驟包括建立
auctionConfig
物件。如此一來,賣方就能指定應參與競價的買方,並在產生出價或廣告評分期間提供任何可能相關的信號。 - 呼叫
navigator.runAdAuction()
並傳入在上一個步驟中建立的設定,即可執行競價。這會啟動買方鏈,產生出價並進行評分。這個步驟的最終結果是可以顯示廣告並顯示廣告的候選廣告。 - 在圍欄或 iframe 中顯示勝出的廣告。
- 回報競價結果。有一個函式
navigator.sendReportTo()
會啟動報表,賣方一律會收到競價結果的報表。只有贏得競價的買方會收到報表。此方法會使用本指南先前所述的賣方reportResult()
,向其伺服器回報資料。