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

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

賣家執行的裝置端競價

裝置端 Protected Audience 競價會在銷售廣告空間的網站上執行，而執行競價的當事人就是賣家。許多各方都可能擔任賣方：網站可能會自行執行廣告競價，或納入第三方指令碼來執行競價，也可能使用 SSP，將裝置端競價與其他伺服器端廣告競價活動合併執行。在裝置端廣告競價中，賣方有三項基本工作：

  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|false 布林值，用於指示 runAdAuction() 傳回的 Promise 是否應解析為 FencedFrameConfig (如果為 true，則用於 <fencedframe>)，或是不透明的 urn:uuid URL (如果為 false，則用於 <iframe>)。預設為 false。

以非同步方式提供信號

部分信號的值 (由 auctionSignals、sellerSignals、perBuyerSignals 和 perBuyerTimeouts 欄位設定) 可以選擇不以具體值提供，而是以 Promise 提供。這樣一來，競價的某些部分 (例如載入指令碼和信任信號，以及啟動獨立工作站程序) 就能與這些值的運算 (或網路擷取) 重疊。工作站指令碼只會看到已解析的值；如果任何這類 Promise 遭到拒絕，除非拍賣已失敗或以其他方式取消，否則拍賣會中止。

設定有多位賣家的競價

在某些情況下，多位賣家可能會想參與競價，而個別競價的得標者會進入由其他賣家執行的另一場競價。這些傳送的個別競價稱為「元件競價」。為利於進行這些元件競價，componentAuctions 物件可包含每個賣家元件競價的其他競價設定。這些元件競價的得標出價會傳遞至「頂層」競價，由頂層競價最終決定競價結果。元件競價的 auctionConfig 可能沒有自己的 componentAuctions。如果 componentAuctions 不為空，interestGroupBuyers 就不得有任何內容。也就是說，在任何特定的受保護的目標對象競價中，不是只有單一賣家且沒有元件競價，就是所有出價都來自元件競價，且頂層競價只能從元件競價的得標者中選擇。

執行競價

賣方呼叫 navigator.runAdAuction()，向使用者瀏覽器發出要求，開始進行廣告競價。

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

runAdAuction() 呼叫會傳回 Promise，該 Promise 會解析為廣告。發布商網頁上的任何程式碼，都無法檢查勝出的廣告，或從 runAdAuction() 的結果中瞭解廣告內容。如果 resolveToConfig 標記在 AuctionConfig 中設為 true，系統會傳回 FencedFrameConfig 物件，該物件只能在設有安全防護的影格中算繪。如果旗標設為 false，系統會傳回不透明的 URN，可在 iframe 中算繪。runAdAuction 可能會傳回空值，表示未選取任何廣告。在這種情況下，賣家可能會選擇放送指定相關內容的廣告。