在發布商頁面和 #39 頁面上設定廣告競價

瞭解如何設定 Protected Audience API 競價。

賣方執行的裝置端競價

裝置端 Protected Audience 競價會在販售廣告空間的網站上運作 是指以賣方身分執行競價的一方許多方可能是 賣方：網站可能會自行執行廣告競價，也可能包含 指令碼來執行競價，或者採用結合執行 和其他伺服器端廣告競價活動，參與裝置端競價。賣家 需要在裝置端廣告競價中導入三項基本工作：

  1. 賣方決定 (a) 哪些買方可以參與，以及 (b) 出價 來自這些買方興趣群組有資格參加競價。這樣一來， 賣方強制執行網站規則，決定哪些廣告允許顯示在 頁面。
  2. 賣方負責競價的商業邏輯：JavaScript 這個程式碼會考量每筆出價的價格和中繼資料，並且計算 「理想性」分數理想的出價將贏得 競價。
  3. 賣方製作競價結果報表，包括 清償價格和任何其他款項得標和落選買家也能獲得 自行製作報表

本文將說明如何設定及啟動裝置端競價。

設定 Protected Audience API 廣告競價

如要執行 Protected Audience API 廣告競價，第一步是 設定競價方法是建立 auctionConfig 物件。 以下是這類設定的範例：

const auctionConfig = {
  seller: 'https://seller.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://buyer-1.example', 'https://buyer-2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://buyer-1.example': {...},
    'https://buyer-2.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://buyer-1.example': 50,
    'https://buyer-2.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://component-seller.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ],
  resolveToConfig: [true|false],
};

AuctionConfig 個房源

必要屬性

auctionConfigs 的唯一必要屬性是 seller。 decisionLogicUrl和interestGroupBuyers。

屬性 範例 角色
seller https://seller.example 賣方的來源。
decisionLogicUrl https://seller.example/decision-logic.js 競價 JavaScript 決策邏輯小工具的網址。這個欄位的來源必須與賣方欄位相同。
interestGroupBuyers [https://buyer-1.example,
https://buyer-2.example,
...]		 要求參與競價的所有興趣群組擁有者來源

選用屬性

auctionConfigs 的其他屬性為選用屬性。

屬性 範例 角色
trustedScoringSignalsUrl https://seller.example/scoring-signals 賣家鍵/值伺服器的網址。系統會使用廣告素材的顯示網址做為鍵，在廣告評分程序期間查詢這項資訊。這個欄位的來源必須與賣方欄位相同。
auctionSignals {"category":"news"} JSON 可序列化物件，代表參與競價的所有買方和賣方可用的信號。
sellerSignals {...} JSON 可序列化物件，代表僅供賣家使用的信號。
perBuyerSignals {https://dsp.example: {...}、
https://another-buyer.example: {...},
... }		 可供特定買方使用的信號。這些信號可能來自賣方或買方。
perBuyerTimeouts {https://www.example-dsp.com: 50,
https://www.another-buyer.com: 200,
*：150、
...}、		 特定買方 generateBid() 指令碼的執行階段上限 (以毫秒為單位)。凡是未定義特定逾時的買方，都會套用萬用字元符號。
sellerTimeout 100 賣方 scoreAd() 指令碼的執行時間上限，以毫秒為單位。
componentAuctions [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] 元件競價的其他設定。
resolveToConfig 是|否 布林值，如果 true (用於 <fencedFrame> 中)，會將 runAdAuction() 傳回的承諾解析為 FencedFrameConfig，如果為 false，則導向至不透明的 urn:uuid 網址 (適用於 <iframe>)。預設值為 false。

以非同步方式提供信號

部分信號的值 (由 auctionSignals 設定、 sellerSignals、perBuyerSignals 和 perBuyerTimeouts 欄位) 可以 非必要時不一定要提供具體值，而是 Promise。這麼做 競價的某些部分 (例如載入指令碼和受信任的信號)，以及 啟動獨立的工作區程序，以重疊運算作業 (或稱網路) 擷取) 這些值。Worklet 指令碼只會檢查 價值；如果有任何此類 Promise 被拒絕，競價將會取消，除非該 Promise 遭到拒絕 以失敗或以其他方式取消。

設定由多個賣方參與的競價

在某些情況下，可能會有多個賣方想參與競價， 各個競價的勝出者進入另一次競價 賣方這些個別贏得的競價稱為元件競價。 如要促進這些元件競價，componentAuctions 物件可以包含 以及每個賣方的競價設定。 各構成競價的勝出出價將傳遞至 「頂層」以及競價的最終決定 元件競價可能有 auctionConfig 沒有自己的競價 componentAuctions。當 componentAuctions 不是空白時 interestGroupBuyers必須留空。也就是 目標對象競價：只有一個賣方且沒有元件競價 所以所有出價都來自元件競價 從元件的競價中選出贏家。

執行競價

賣方藉由以下方式，向使用者的瀏覽器發出請求並啟動廣告競價： 正在撥打 navigator.runAdAuction()。

try {
  const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
  // Handle error.
}

runAdAuction() 呼叫會傳回可解析廣告的 Promise。不 以便檢查勝出的廣告 否則從 runAdAuction() 的結果中瞭解其內容。如果 AuctionConfig 中的 resolveToConfig 旗標設為 true， 傳回的 FencedFrameConfig 物件只能顯示在圍欄內 相框。如果旗標設為 False，系統會傳回不透明 URN，這可以 在 iframe 中呈現的。runAdAuction 可能會傳回空值 表示沒有選取任何廣告。在這種情況下，賣方可以選擇 顯示內容比對廣告。