賣方指南：參與廣告競價

Protected Audience API 廣告競價的賣家 API 指南和參考資料。

本文提供廣告競價的技術參考資料，可用於目前的 Protected Audience API 實驗版本。

請參閱開發人員指南，瞭解 Protected Audience API 的完整生命週期，並參閱 Protected Audience API 說明，深入探討賣方如何執行裝置端競價。

不是開發人員嗎？請參閱 Protected Audience API 總覽。

Protected Audience API 廣告競價是什麼？

Protected Audience API 廣告競價是一系列小型 JavaScript 程式，瀏覽器會在使用者裝置上執行這些程式，以便選擇廣告。為保護隱私權，賣方和買方提供的所有廣告競價程式碼都會在隔離的 JavaScript worklet 中執行，無法與外部溝通。

Protected Audience API 廣告競價的六個階段
這張圖表概略說明 Protected Audience API 廣告競價的各個階段。
  1. 使用者造訪顯示廣告的網站。
  2. 賣家的程式碼會執行 navigator.runAdAuction()。這項屬性可指定要販售的廣告空間，以及可出價的對象。賣方也必須加入評分每個出價的劇本，scoreAd()。
  3. 系統會執行受邀買家的程式碼，產生出價、相關廣告素材的網址和其他資料。出價指令碼可從買方的鍵/值服務查詢即時資料，例如剩餘廣告活動預算。
  4. 賣方的程式碼會為每個出價評分，並選出得標者。這個邏輯會使用出價值和其他資料，傳回出價的適當性。無法勝過內容相關勝出的廣告會遭到拒絕。賣方可以使用自己的鍵/值服務取得即時資料。
  5. 系統會以不透明值的形式傳回獲勝廣告，並顯示在圍欄框架中。賣家和發布者都無法查看這個值。
  6. 系統會向賣家和得標買家回報競價結果。

競價何時開始？

Protected Audience API 可單獨執行，也可以搭配程式輔助競價執行。在多賣家程式輔助競價中：

  1. 使用者造訪參與計畫的網站。
  2. 另一位賣家會執行程式輔助競價，為可用的廣告版位找出比對內容廣告。
  3. 執行 Protected Audience API 競價。
  4. scoreAd()會將買方的出價與第一次競價的結果進行比較。

出價若無法勝過內容相關贏家，就會遭到拒絕。

誰會執行 Protected Audience API 廣告競價？

有多方可能會執行競價來銷售廣告空間。

例如：

  • 內容發布商：自行在網站上代管廣告內容。
  • 供應端平台 (SSP)：與發布商合作並提供其他服務。
  • 第三方指令碼：代表發布商參與廣告競價。

使用 Protected Audience API 時，賣家有三項工作：

  • 強制執行發布商規則：哪些買方和出價符合資格。
  • 執行競價邏輯：在 worklet 中執行 JavaScript，計算每個出價的適合度分數。
  • 回報競價結果。

這些工作會以程式輔助方式完成，賣方在透過呼叫 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 說明也提供功能支援和限制的詳細資料。