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

本文件將概略說明如何針對單一賣家，使用 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，這是在競價期間從賣方的 Key/Value 伺服器讀取的信號。平台會使用候選廣告的 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() 向其伺服器回報。