賣方指南：參與廣告競價

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 廣告競價的六個階段
這張圖表列出 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 執行三項工作：

  • 強制執行發布商規則：哪些買方和出價符合資格。
  • 執行競價邏輯：在工作集中執行的 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() 會傳回 Promise，該 Promise 會解析為代表廣告競價結果的 URN (urn:uuid:<something>)。只有在傳遞至封閉架構以進行算繪時，瀏覽器才能解碼，發布商網頁無法檢查勝出的廣告。

decisionLogicUrl 指令碼會逐一考量每個廣告及其相關聯的出價和中繼資料，然後指派數值型偏好分數。

auctionConfig 個房源

seller
必要
範例：'https://ssp.example'
角色：賣方的來源。
decisionLogicUrl
必要
範例：'https://ssp.example/auction-decision-logic.js'
角色：競價 Worklet 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 說明也提供功能支援和限制的詳細資料。