透過瀏覽器執行單一賣方的競價

本文將概要說明如何使用 Protected Audience 資料，為單一賣家執行競價 (目前版本的 Protected Audience API 採用這種做法)。單一賣家的競價可做為更複雜的競價 (涉及多位賣家) 的一部分執行。在這種情況下，單一賣家競價稱為「元件競價」，可為多位賣家參與的「頂層競價」提供廣告候選項目。

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

Protected Audience API 廣告競價的六個階段

1. 使用者造訪顯示廣告的網站。
2. 賣家的程式碼會執行 navigator.runAdAuction()。這項屬性會指定待售的廣告空間，以及可出價的對象。賣家也必須加入腳本，為每個出價評分 scoreAd()。
3. 受邀買方的程式碼會執行，產生出價、相關廣告素材的網址和其他資料。出價指令碼可以從買方的鍵/值服務查詢即時資料，例如廣告活動的剩餘預算。
4. 賣家的程式碼會為每個出價評分，並選出得標者。這項邏輯會使用出價值和其他資料，傳回出價的合適程度。如果廣告無法擊敗內容相關勝出者，就會遭到拒絕。賣方可使用自己的鍵/值服務取得即時資料。
5. 系統會以不透明值形式傳回勝出的廣告，並顯示在設限框架中。賣家和發布者都無法查看這個值。
6. 系統會向賣家和得標買家回報競價結果。

當使用者前往顯示廣告的網頁時，系統可能會進行競價。 系統可能會提前執行競價，確保廣告素材在廣告空位顯示時已準備就緒。

賣方會發起廣告競價、使用以 scoreAd() 函式形式提供的自訂邏輯為候選廣告評分，並負責向自己和勝出買方回報競價結果。賣方也可以使用 scoreAd() 函式強制執行發布商規則，並篩選廣告品質。

賣家可能指的是：

• 內容發布商 (代表自己，在網站上代管廣告內容)
• 供應端平台 (SSP)，與廣告發布商合作並提供其他服務
• 第三方指令碼，代表發布商啟用廣告競價參與資格。

執行競價的必要條件

賣家需要定義兩個 JavaScript 函式才能執行競價：

• scoreAd()，可為廣告候選項目評分
• reportResult()，負責向賣家回報競價結果

這些指令碼必須由賣家擁有的單一端點提供。

scoreAd()

賣方必須定義 scoreAd() 函式，並從他們擁有的端點提供該函式。端點會在競價設定中指定為 decisionLogicUrl。scoreAd() 函式具有下列簽章：

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

scoreAd() 的參數如下：

• adMetaData，這是買方提供的廣告素材任意中繼資料。這是可序列化的 JSON 物件，賣家和買家必須定義並同意其結構。
• bid，代表出價的數值。
• auctionConfig，這是用來執行競價的競價設定。
• trustedScoringSignals，這些信號是在競價期間從賣家的鍵/值伺服器讀取。平台會使用候選廣告的 renderUrl 做為這項查詢的鍵。
• browserSignals，這是由瀏覽器建構的物件，包含瀏覽器已知的資訊，以及賣家競價指令碼可能想驗證的資訊。
• directFromSellerSignals 是物件，可能包含下列欄位： ** sellerSignals：與 auctionConfig.sellerSignals 類似，但使用 directFromSellerSignals 機制傳遞。 ** auctionSignals：與 auctionConfig.auctionSignals 類似，但使用 directFromSellerSignals 機制傳遞。

以下是 browserSignals 的範例。請注意，候選廣告的 renderUrl 可透過下列信號取得：

{ 'topWindowHostname': 'www.example-publisher.com',
  'interestGroupOwner': 'https://www.example-buyer.com',
  'renderURL': 'https://cdn.com/render_url_of_bid',
  'renderSize': {width: 100, height: 200}, /* if specified in the bid */
  'adComponents': ['https://cdn.com/ad_component_of_bid',
                   'https://cdn.com/next_ad_component_of_bid',
                   ...],
  'biddingDurationMsec': 12,
  'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
  'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}

reportResult()

賣方必須定義 reportResult() 函式，並從他們擁有的端點提供。端點會在競價設定中指定為 decisionLogicUrl。reportResult() 函式具有下列簽章：

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

reportResult() 的參數如下：

• auctionConfig，這是用來執行競價的競價設定。
• browserSignals，這是由瀏覽器建構的物件，包含瀏覽器已知的資訊，賣家的競價指令碼可能會想驗證這些資訊。這是傳遞至 scoreAds() 函式的相同物件。

reportResult() 會傳回 signalsForWinner，這是任意 JSON 物件，會傳遞至得標買家的報表函式。這應包括賣方可提供的任何相關競價資訊，供買方製作報表。

執行 Protected Audience API 競價

賣家必須完成四個主要步驟，才能執行競價。請注意，這些步驟假設賣家已設定端點，可傳回本指南先前提及的必要 JavaScript。

1. 設定競價。這個步驟包括建立 auctionConfig 物件。這可讓賣方指定應參與競價的買方，並在出價產生或廣告評分期間提供任何相關信號。
2. 呼叫 navigator.runAdAuction() 並傳入上一個步驟中建立的設定，執行競價。這會啟動一連串的買家出價和評分程序。這個步驟的最終結果是廣告候選項目，可供顯示廣告。
3. 在設有圍欄的影格或 iframe 中轉譯勝出的廣告。
4. 回報競價結果。有一個函式 navigator.sendReportTo() 會啟動回報程序。賣家一律會收到競價結果報表。只有贏得競價的買方會收到報表。這會使用本指南稍早所述的賣家 reportResult()，向賣家伺服器回報。