Protected Audience API 廣告競價的 Seller API 指南和參考資料。
本文將說明廣告競價的技術參考資料 (如同目前的 Protected Audience API 現行疊代版本)。
閱讀開發人員指南,瞭解完整生命週期 請參閱 Protected Audience API 說明,進一步瞭解 瞭解賣方如何執行裝置端競價。
您不是開發人員嗎?請參閱「Protected Audience API 總覽」。
什麼是 Protected Audience API 廣告競價?
Protected Audience API 廣告競價是一組小型 JavaScript 程式, 以便選擇廣告。為保障隱私權,所有廣告 賣方和買方的競價程式碼是在獨立的 JavaScript 中執行 無法直接和遠端連線的 worklet 也不是世界末日
![Protected Audience API 廣告競價的六個階段](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/six-stages-a-protected-a-3e1dd6fdeddbe.png?authuser=9&hl=zh-tw)
- 使用者造訪顯示廣告的網站。
- 賣方的程式碼執行
navigator.runAdAuction()
。這可指定 廣告空間銷售,以及可出價的對象。銷售員也必須加入指令碼 為每次出價評分,scoreAd()
。 - 受邀買方的程式碼執行,以產生出價和相關廣告的網址 廣告素材等資料出價指令碼可以查詢即時資料 例如剩餘廣告活動預算 鍵/值服務:
- 賣方的代碼會為每次出價評分,並選出勝出者。此邏輯會使用 出價和其他資料會傳回出價的合適度。達成競價的廣告 內容相關廣告的勝出組合就會遭到拒絕賣方可以使用自己的 即時資料的鍵/值服務。
- 勝出的廣告會以不透明值的形式傳回,並在 圍欄頁框。賣方和 發布商將無法查看這個值。
- 系統會向賣方和得標買方回報競價內容。
競價何時進行?
Protected Audience API 可以單獨執行,也可以與程式輔助競價一併執行。如果是多重賣方 程式輔助競價
- 使用者造訪參與計畫的網站。
- 其他賣方會舉辦程式輔助競價,為可用的廣告版位尋找內容相關廣告。
- 系統會執行 Protected Audience API 競價。
scoreAd()
比較買家的出價與第一次競價的結果,
無法擊敗內容相關勝出者的出價會遭到拒絕。
誰會進行 Protected Audience API 廣告競價?
許多方可能會進行競價來銷售廣告空間。
例如:
- 內容發布商:自行在網站上代管廣告素材。
- 供應端平台 (SSP):與發布商合作並提供其他服務。
- 第三方指令碼:供發布商參與廣告競價。
使用 Protected Audience API 時,賣方可執行三項工作:
- 執行發布商規則:哪些買方以及哪些出價符合資格。
- 執行競價邏輯:JavaScript 執行 worklet 來計算 每次出價的理想成效分數
- 回報競價結果。
這些工作是透過程式或賣方提供的程式碼中完成
呼叫 JavaScript 函式以模擬廣告競價
navigator.runAdAuction()
。
API 函式
runAdAuction()
賣方呼叫 navigator.runAdAuction()
向使用者的瀏覽器發出請求,以開始廣告競價。
例如:
const auctionConfig = {
seller: 'https://ssp.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://dsp.example': {...},
'https://another-buyer.example': {...},
...
},
perBuyerTimeouts: {
'https://dsp.example': 50,
'https://another-buyer.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://some-other-ssp.example',
'decisionLogicUrl': ...,
...
},
...
]
};
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
runAdAuction()
會傳回可解析為 URN (urn:uuid:<something>
) 的承諾,
廣告競價結果。只有在傳遞至圍欄頁框時,瀏覽器才能解碼這個影格
以便顯示:發布商網頁無法檢查勝出的廣告。
decisionLogicUrl
指令碼會考量每則廣告及其中的
相關出價和中繼資料 (一次一個),然後指定數值
以及客戶意願分數
auctionConfig
個房源
seller
- 必填
- 範例:
'https://ssp.example'
- 角色:賣方的來源。
decisionLogicUrl
- 必填
- 範例:
'https://ssp.example/auction-decision-logic.js'
- 角色:競價小程式 JavaScript 的網址。
trustedScoringSignalsUrl
- 選填
- 範例:
'https://ssp.example/scoring-signals'
- 角色:賣家受信任伺服器的網址。
interestGroupBuyers
- 必填
- 範例:
['https://dsp.example', 'https://buyer2.example', ...]
- 角色:要求參與競價的所有興趣群組擁有者來源。 ,瞭解如何調查及移除這項存取權。
- 注意:賣方可以指定
interestGroupBuyers:
,允許所有興趣群組出價。然後根據興趣群組擁有者以外的條件決定是否接受廣告。舉例來說,賣方可以查看廣告素材是否符合他們的政策規定。 auctionSignals
- 選填
- 範例:
{...}
- 角色:賣家資訊,如頁面情境、競價類型等。
sellerSignals
- 選填
- 範例:
{...}
- 角色:根據發布商設定,提出內容相關廣告請求等資訊
sellerTimeout
- 選填
- 範例:
100
- 角色:賣方
scoreAd()
指令碼的執行階段上限 (毫秒)。 perBuyerSignals
- 選填
- 範例:
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
- 角色:每個買方在自家伺服器中,與個別買方的網頁比對內容信號。
perBuyerTimeouts
- 選填
- 範例:
50
- 角色:特定買方
generateBid()
指令碼的執行階段上限 (毫秒)。 componentAuctions
- 選填
- 範例:
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
- 角色:元件競價的其他設定。
decisionLogicUrl
decisionLogicUrl
是競價設定物件的屬性。
已傳遞至 runAdAuction()
。此網址必須包含
scoreAd()
函式。這個邏輯會針對每則廣告
以確定它的預期性
scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
...
return desirabilityScoreForThisAd;
}
browserSignals
browserSignals
是瀏覽器建構的物件,包括
瀏覽器知道,以及賣方競價指令碼
驗證:
{
topWindowHostname: 'publisher.example',
interestGroupOwner: 'https://dsp.example',
renderUrl: 'https://cdn.example/render',
adComponents: ['https://cdn.com/ad-component-1', ...],
biddingDurationMsec: 12,
dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}
競價開始之前,賣方會找出最適合
可用的廣告版位。scoreAd()
邏輯的部分內容會拒絕任何無法播放的廣告
贏過內容相關廣告的勝出組合。
scoreAd()
scoreAd()
會使用下列引數:
引數 | 角色 |
---|---|
adMetadata |
買方提供的任意中繼資料。 |
auctionConfig |
傳遞至 navigator.runAdAuction() 的競價設定物件。 |
bid |
以數值表示的出價金額。 |
trustedScoringSignals |
在競價期間從賣方受信任伺服器擷取的值,代表賣方的廣告意見。 |
常見問題
競價得標者如何決定競價勝出者,並由誰挑選?
賣方會提供評分邏輯來決定每則廣告的意願分數,瀏覽器則會選取最高分數做為勝出廣告。
賣方在 scoreAd()
函式中加入邏輯,而瀏覽器會在對函式外程式碼有限的通訊小程式中執行函式。瀏覽器本身不會為廣告評分。瀏覽器只負責執行評分邏輯,並選取分數最高的出價。
所有 Protected Audience API 參考資料
可用的 API 參考指南如下:
- Protected Audience API 的開發人員指南。
- 廣告買方指南:Protected Audience 興趣群組與出價產生。
- Protected Audience 廣告競價的廣告賣方指南。
- 製作競價結果報表指南
- Protected Audience 廣告競價延遲的最佳做法
- 排解 Protected Audience 相關問題
Protected Audience API 說明也提供功能支援和限制的詳細資料。