本頁面由 Cloud Translation API 翻譯而成。

賣方指南：參與廣告競價

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

本文將說明廣告競價的技術參考資料，如同目前實驗的 Protected Audience API 版本所述。

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

如果您不是開發人員，請參閱「Protected Audience API 總覽」。

什麼是 Protected Audience API 廣告競價？

Protected Audience API 廣告競價是一組小型 JavaScript 程式，瀏覽器會在使用者裝置上執行，以選擇廣告。為保護隱私權，賣方和買方的所有廣告競價程式碼都會在無法與外部通訊的獨立 JavaScript 指令碼中執行。

Protected Audience API 廣告競價的六個階段 — 此圖表概略說明 Protected Audience API 廣告競價的各個階段。

使用者造訪顯示廣告的網站。
賣方的程式碼會執行 navigator.runAdAuction()。這個欄位會指定要銷售和出價的對象。賣方也必須包含為每個出價評分的指令碼 (scoreAd())。
注意：競價開始前，賣方會找出最適合可用廣告版位的內容相關廣告。
受邀買方的程式碼會執行出價、相關廣告素材的網址及其他資料。出價指令碼可查詢來自買家鍵/值服務的即時資料，例如剩餘廣告活動預算。
賣方程式碼會計算每個出價並選出勝出者。這個邏輯會使用出價值，其他資料則會傳回出價的理想結果。無法勝過內容相關勝出者的廣告會遭到拒絕。賣方可以使用自己的鍵/值服務處理即時資料。
勝出的廣告會以不透明值的形式傳回，該值會顯示在圍欄頁框中。賣方和發布商皆無法查看這個值。
系統會將競價回報給賣方和得標買方。
注意：賣方的 reportResult() 和買方的 reportWin() 可包含對 sendReportTo() 的呼叫。這項功能會暫時提供，直到私密匯總功能提供匯總報表為止。

競價何時進行？

Protected Audience API 可以單獨執行，也可透過程式輔助競價執行。在多重賣方的程式輔助競價中：

使用者造訪參與的網站。
程式輔助競價是由另一個賣方執行，為可用的廣告版位尋找內容相關廣告。
系統會執行 Protected Audience API 競價。
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() 會傳回承諾，可解析為代表廣告競價結果的 URN (urn:uuid:<something>)。只有在將這個參數傳遞至圍欄頁框進行算繪時，瀏覽器才能進行解碼：發布商頁面無法檢查勝出的廣告。

注意：含有 joinAdInterestGroup() 的指令碼來源必須與興趣群組擁有者的來源相符，因此除非興趣群組擁有者的來源與目前的文件來源 (例如擁有專屬興趣群組的網站) 與目前的文件來源相符，否則必須透過 iframe 呼叫 joinAdInterestGroup() (例如來自需求端平台)。runAdAuction 的需求不同，因此使用 <script> 標記的效果可能遠比跨來源 iframe 要更高。

decisionLogicUrl 指令碼會一次考量每則廣告及其關聯出價和中繼資料，然後為其指派數值分數。

`auctionConfig` 個房源

注意：目前的 Protected Audience API 實作不支援 additionalBids。詳情請參閱 Protected Audience API 說明中的「競價參與者」一節。

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 的開發人員指南。
廣告買方指南：Protected Audience 興趣群組與出價產生。
Protected Audience 廣告競價的廣告賣方指南。
製作競價結果報表指南
Protected Audience 廣告競價延遲的最佳做法
排解 Protected Audience 相關問題

Protected Audience API 說明也提供功能支援和限制的詳細資料。