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

賣方指南：參與廣告競價

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 廣告競價的六個階段 — 此圖表概述 Protected Audience API 廣告競價的各個階段。

使用者造訪顯示廣告的網站。
賣方的程式碼執行 navigator.runAdAuction()。這可指定廣告空間銷售，以及可出價的對象。銷售員也必須加入指令碼為每次出價評分，scoreAd()。
注意：競價開始前，賣方會找出最適合可用的廣告版位。
受邀買方的程式碼執行，以產生出價和相關廣告的網址廣告素材等資料出價指令碼可以查詢即時資料例如剩餘廣告活動預算鍵/值服務：
賣方的代碼會為每次出價評分，並選出勝出者。此邏輯會使用出價和其他資料會傳回出價的合適度。達成競價的廣告內容相關廣告的勝出組合就會遭到拒絕賣方可以使用自己的即時資料的鍵/值服務。
勝出的廣告會以不透明值的形式傳回，並在圍欄頁框。賣方和發布商將無法查看這個值。
系統會向賣方和得標買方回報競價內容。
注意：賣方的 reportResult() 和買方 reportWin() 可包含呼叫至 sendReportTo()。有這個選項。暫時，直到產生匯總報表為止私人匯總：

競價何時進行？

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>) 的承諾，廣告競價結果。只有在傳遞至圍欄頁框時，瀏覽器才能解碼這個影格以便顯示：發布商網頁無法檢查勝出的廣告。

注意：含有 joinAdInterestGroup() 的指令碼來源必須與興趣群組擁有者的來源相符，因此 joinAdInterestGroup() 會必須由 iframe (例如 DSP) 呼叫，除非興趣群組擁有者與目前文件的來源相符 ( 例如有自己的興趣群組的網站)。 runAdAuction不同因此，使用 <script> 標記的效果可能遠比跨來源 iframe。

decisionLogicUrl 指令碼會考量每則廣告及其中的相關出價和中繼資料 (一次一個)，然後指定數值以及客戶意願分數

`auctionConfig` 個房源

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

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 說明也提供功能支援和限制的詳細資料。