處理要求

當 Google 將出價要求傳送至您的應用程式時，即時出價互動就會開始。本指南說明如何編寫應用程式程式碼，以處理出價要求。

剖析要求

Google 會以 OpenRTB JSON 或 Protobuf 格式序列化出價要求，並以 HTTP POST 要求的酬載形式附加。收到的格式取決於端點的設定。如需範例，請參閱「出價要求範例」。

您必須剖析這項要求，才能接收序列化的 BidRequest。如果您使用 Protobuf 格式，請務必從參考資料頁面下載 openrtb.proto 和 openrtb-adx.proto，並使用這些檔案產生程式庫，用於剖析 BidRequest 訊息。舉例來說，下列 C++ 程式碼會剖析字串中的 POST 酬載，藉此剖析要求：

string post_payload = /* the payload from the POST request */;
BidRequest bid_request;
if (bid_request.ParseFromString(post_payload)) {
  // Process the request.
}

取得 BidRequest 後，您就可以將其視為物件，擷取並解讀所需欄位。舉例來說，在 C++ 中，疊代 OpenRTB `BidRequest` 中的交易可能如下所示：

for (const BidRequest::Imp::Pmp::Deal& deal : pmp.deals()) {
  DoSomething(deal.id(), deal.wseat());
}

帳單 ID

當發布商的廣告空間符合您一或多項 預先指定設定時，您就會收到出價要求。BidRequest.imp.ext.billing_id 會填入所有符合資格買方的帳單 ID，以及相關的預先指定目標設定。此外，如果是交易廣告空間，您可以使用 BidRequest.imp.pmp.deal.ext.billing_id 找出與相關買方相關聯的帳單 ID。出價時，只能指定出價要求中買家的帳單 ID。

如果出價要求中包含多個帳單 ID，您必須使用 BidResponse.seatbid.bid.ext.billing_id 欄位，指定要將出價歸給哪個買方的帳單 ID。

imp {
  ext {
    // The billing IDs of all of your matching pretargeting configs and eligible child seats are
    // stored in a flat list here.
    billing_id: 123
    billing_id: 456
    billing_id: 789
  }
  pmp {
    // All eligible deals are stored in a single flat list.
    deal {
      id: 1000
      ext {
        // The specific billing IDs eligible to bid on this deal are indicated here.
        billing_id: 789
      }
      ...
    }
    deal {
      id: 2000
      ext {
        billing_id: 123
        billing_id: 456
      }
      ...
    }
  }
  ...
}
...

判斷已封鎖的類別

出價時，內含的廣告素材不得有發布商封鎖的類別。否則出價會從競價中篩除。

如要查看曝光的封鎖類別，請檢查 BidRequest.bcat 欄位，其中會填入為帳戶設定的分類。

以下範例顯示根據已設定的廣告類別分類封鎖的類別：

IAB 內容分類 1.0 版

// Bid request
{
  // Indicates the blocked categories using IAB Content 1.0 Taxonomy.
  "bcat": [
    "IAB9-9",  // Cigars
    "IAB8-18"  // Wine
  ]
  "imp": {
    ...
  }
}
      
// Bid request
{
  // Indicates the blocked categories using Google Ad Category Taxonomy.
  "bcat": [
    "10138",  // Cigar and tobacco collecting
    "10080",  // Tobacco
    "11649",  // Wine
    "10674",  // Wine collecting
    "13008"   // Wine clubs
  ]
  "imp": {
    ...
  }
}

字典檔案

出價要求會使用字典檔案中定義的 ID，這些 ID 可在參考資料頁面中找到。

競價工具網址巨集

您也可以視需要使用巨集，將 BidRequest 的部分資訊插入出價端點網址。如果您使用一或多個巨集設定端點網址，系統會在出價要求中提供相關資訊時展開巨集。舉例來說，如果您想根據 BidRequest 中的資訊執行負載平衡，這項功能就非常實用。如要要求支援新巨集，請與您的帳戶管理員聯絡。

巨集說明
%%GOOGLE_USER_ID%%

請改用 BidRequest.user.id 中的 Google 使用者 ID。舉例來說，出價者網址 http://google.bidder.com/path?gid=%%GOOGLE_USER_ID%% 會在要求時替換為 http://google.bidder.com/path?gid=dGhpyBhbiBleGFtGxl。

如果 Google 使用者 ID 不明，系統會代入空字串，結果類似於

http://google.bidder.com/path?gid=
%%HAS_MOBILE%%

改為 1，表示出價要求來自行動裝置，否則為 0。這是根據 BidRequest.device.devicetype 的值而定，其中行動裝置以 HIGHEND_PHONE (4) 或 Tablet (5) 表示。
%%HAS_VIDEO%%

改用 1 表示出價要求含有影片廣告空間，或改用 0 表示出價要求不含影片廣告空間。這取決於出價要求中是否填入 BidRequest.imp.video。
%%HOSTED_MATCH_DATA%%

根據 BidRequest.user.buyeruid 替換為值。

%%MOBILE_IS_APP%%

改用 1 表示出價要求適用於行動應用程式廣告空間，否則使用 0。這取決於是否已填入 BidRequest.app。

從交易網址找出行動應用程式 ID

行動應用程式交易會回報類似下列的網址：

mbappgewtimrzgyytanjyg4888888.com

使用 base-32 解碼器解碼粗體部分的字串 (gewtimrzgyytanjyg4888888)。

您可以使用線上解碼器，但必須將字母大寫，並將尾端的 8 替換為 = 值。

因此，解碼這個值： 

GEWTIMRZGYYTANJYG4======
 結果： 
1-429610587
 字串 429610587 是 iOS 應用程式「iFunny」iFunny的應用程式 ID。

以下再舉一例。遭檢舉的網址為： 

mbappgewtgmjug4ytmmrtgm888888.com
 解碼這個值： 
GEWTGMJUG4YTMMRTGM======
 結果： 
1-314716233
 結果 314716233 是 iOS 應用程式「TextNow」TextNow的應用程式 ID。

從交易網址找出行動應用程式名稱

以下是取得應用程式名稱的範例。遭檢舉的網址如下： 

mbappMFUXELTDN5WS42DZOBQWQLTJN4XHG3DJORUGK4Q888.com
 解碼這個值： 
MFUXELTDN5WS42DZOBQWQLTJN4XHG3DJORUGK4Q===
 結果： 
air.com.hypah.io.slither
 結果等同於 Android 應用程式 slither.io。

公開出價欄位

傳送給參與公開出價的廣告交易平台和聯播網出價者的出價要求，與傳送給參與標準即時出價的 Authorized Buyers 類似。公開出價客戶會收到少數額外欄位，而現有欄位也可能會有其他用途。包括：

OpenRTB 詳細資料
BidRequest.imp.ext.dfp_ad_unit_code

包含發布商的 Ad Manager 聯播網代碼，後面接著廣告單元階層，並以正斜線分隔。

舉例來說，這會以類似下列格式顯示： /1234/cruises/mars。
BidRequest.user.data.segment

發布商傳送給廣告交易平台出價者的重複鍵/值組合。

您可以判斷這些值是發布商在 BidRequest.user.data.name 設為 “Publisher Passed” 時傳送的鍵/值組合。

聲明允許的供應商

提供研究、再行銷和廣告放送等服務的技術供應商，可能會在買賣雙方的互動中扮演某種角色。只有經過 Google 審查，可參與 Authorized Buyers 互動的供應商才能使用。

如要瞭解BidRequest並建立BidResponse，您需要瞭解宣告技術供應商的兩種不同方式：

  1. 部分供應商不需要聲明，這些供應商會列在 Ad Manager 認證外部供應商中。
  2. 其他供應商必須在 BidRequest:
    • 在 BidRequest 中，「BidRequest.imp.ext.allowed_vendor_type」欄位會指定賣家允許的供應商。將在 allowed_vendor_type 中傳送的供應商會列於 vendors.txt 字典檔案中。

出價要求範例

下列範例代表 Protobuf 和 JSON 要求的可讀取範例。

OpenRTB Protobuf

OpenRTB JSON

如要將出價要求轉換為二進位形式 (如同在實際要求中從 POST 酬載取得的形式)，您可以執行下列操作 (以 C++ 為例)。不過請注意，這不適用於 OpenRTB JSON。

string text_format_example = /* example from above */;
BidRequest bid_request;
if (TextFormat::ParseFromString(text_format_example, &bid_request)) {
  string post_payload;
  if (bid_request.SerializeToString(&post_payload)) {
    // post_payload is a binary serialization of the protocol buffer
  }
}

即時意見回饋

Authorized Buyers 以及使用公開出價的廣告交易平台和聯播網，都能取得即時意見回饋。

系統會根據您先前出價的結果，在 BidRequest.ext.bid_feedback 中填入即時意見回饋，並提供競價得標與否，或得標所需的最低出價等詳細資料。如要啟用即時意見回饋，請與客戶經理聯絡。

除了出價回應意見回饋中傳送的預設欄位，您也可以使用 BidResponse.seatbid.bid.ext.event_notification_token 欄位，在出價回應中傳送自訂資料。event_notification_token 是只有出價者知道的任意資料，可能有助於偵錯，例如：代表新策略的新指定目標 ID 或出價 ID，或是只有出價者知道的廣告素材相關中繼資料。詳情請參閱 OpenRTB 擴充功能通訊協定緩衝區檔案。

Authorized Buyers 將出價要求傳送給出價方後，出價方會回覆 BidResponse。如果出價方已啟用即時意見回饋，Authorized Buyers 會在後續出價要求中，透過 BidFeedback 訊息傳送回應意見回饋：

message BidFeedback {
  // The unique id from BidRequest.id.
  optional string request_id = 1;

  // The status code for the ad. See creative-status-codes.txt in the
  // technical documentation for a list of ids.
  optional int32 creative_status_code = 2;

  // Deprecated. This field is not populated and will be removed after March,
  // 2025. If the bid won the auction, this is the price paid in your account
  // currency. If the bid participated in the auction but was out-bid, this
  // is the CPM that should have been exceeded in order to win. This is not
  // set if the bid was filtered prior to the auction, if the publisher or
  // winning bidder has opted out of price feedback or if your account has
  // opted out of sharing winning prices with other bidders. For first-price
  // auctions, minimum_bid_to_win is populated instead of this field.
  optional double price = 3 [deprecated = true];

  // The minimum bid value necessary to have won the auction, in your account
  // currency. If your bid won the auction, this is the second highest bid
  // that was not filtered (including the floor price). If your bid didn't win
  // the auction, this is the winning candidate's bid. This field will only be
  // populated if your bid participated in a first-price auction, and will not
  // be populated if your bid was filtered prior to the auction.
  optional double minimum_bid_to_win = 6;

  // Billable event rate multiplier that was applied to this bid during
  // ranking. The adjustment reflects the likelihood that your bid would
  // generate a billable event (namely, the ad renders successfully) if it won
  // the auction, relative to the probability that other bids generate a
  // billable event if they won the auction. This adjustment can be larger or
  // smaller than 1. This affects the final ranking in the auction only; in
  // particular, this multiplier does not affect the payment or whether the
  // bid clears any floor price.
  optional float billable_event_rate_bid_adjustment = 13 [default = 1];

  // When a publisher uses an RTB auction and waterfall-based SDK mediation on
  // the same query, the winner of the real-time auction must also compete in
  // a mediation waterfall (which is ordered by price) to win the impression.
  // If the bid participated in the auction and there was no waterfall, the
  // value of this field is 0. If the bid participated in the auction and
  // there was a waterfall, the value of this field is a price representing a
  // sample bid from the eligible mediation networks that were higher than the
  // auction winner, weighted by expected fill rate. This field can be used
  // in conjunction with minimum_bid_to_win to train bidding models. The CPM
  // is in your account currency.
  optional double sampled_mediation_cpm_ahead_of_auction_winner = 8;

  message EventNotificationToken {
    // The contents of the token.
    optional string payload = 1;
  }

  // The token included in the corresponding bid.
  optional EventNotificationToken event_notification_token = 4;

  // The creative ID included in the corresponding bid.
  optional string buyer_creative_id = 5;
}

在這則訊息中，您應檢查的第一個欄位是 bid_feedback.creative_status_code；您可以在 creative-status-codes.txt 中找到代碼的意義。請注意，如果贏得競價，您可以選擇不提供價格意見。詳情請參閱如何停用。

即時意見回饋包含出價要求 ID 和下列其中一項：

競價結果 即時意見回饋
買方未提交出價。 不會發生任何事情。
買方提交的出價在進入競價前遭到篩除。 廣告素材狀態代碼 (creative-status-codes.txt)。
買方已提交出價，但最後落選。 廣告素材狀態代碼 79 (在競價中出價遭超越)。
買方提交的出價贏得競價。 結算價格和廣告素材狀態碼 1。

如果應用程式曝光和廣告素材狀態代碼為 83，則應用程式發布商可能使用了中介服務瀑布流，因此得標出價會與發布商回傳瀑布流鏈中的其他需求競爭。瞭解如何使用 sampled_mediation_cpm_ahead_of_auction_winner 出價。

範例

以下是支援通訊協定中顯示的即時意見回饋範例：

OpenRTB Protobuf

OpenRTB JSON

為最高價得標競價建立出價模式

在最高價得標競價中出價後，如果出價未遭競價篩除，您會收到即時意見回饋，包括 minimum_bid_to_win 和 sampled_mediation_cpm_ahead_of_auction_winner 欄位。您可以根據這些信號，調整出價邏輯，瞭解出價金額應提高或降低多少，才能贏得曝光。

  • minimum_bid_to_win：贏得即時競價的最低出價。如果您贏得競價，這就是您在贏得競價時可設定的最低出價。如果未得標，這就是得標出價。
  • sampled_mediation_cpm_ahead_of_auction_winner：如果中介服務鏈中還有其他聯播網，這個欄位的值就是代表其中一個符合資格的中介服務聯播網的範例出價，該出價高於競價勝出者，並根據預期供應率加權計算。如果中介服務鏈中的任何聯播網都不會填補，或發布商未使用 SDK 中介服務，則此值會設為 0。

運作方式

如要說明用於判斷 minimum_bid_to_win 和 sampled_mediation_cpm_ahead_of_auction_winner 可能值的計算方式，我們首先需要定義下列項目：

  • 以下是中介服務鏈中的千次曝光出價，依遞減順序排列：
    \[C_1, C_2, …, C_n\]
  • 以下代表中介服務鏈中千次曝光出價的相應填補率：
    \[f_1, f_2, …, f_n\]
  • 以下函式用於根據指定的填滿率，從中介服務鏈結元素 \(i\)判斷預期千次曝光出價及其機率：
    \(X_i = \{C_i\) 機率 \(f_i\)； \(0\) 機率 \(1 - f_i\}\)
  • 最終勝出的中介服務鏈為：
    \[\{C_1, C_2, …, C_K, W\}\]
    其中 \(W\) 是勝出出價，而 \(C_K > W >= C_{K+1}\)
  • 預留價格或底價以 \(F\)表示。
  • 次高出價會標示為 \(R\)。
競價得標者計算
欄位 計算方式
minimum_bid_to_win
\(max\{F, R, X_{K+1}, …, X_n\}\)
sampled_mediation_cpm_ahead_
of_auction_winner
\(\{C_i\) 具有機率 \(\prod_{j=1}^{i-1}(1-f_j) \cdot f_i \div \prod_{j=1}^{K}(1-f_j)\}\)
這是 \(1 <= i <= K\)方案。
競價失敗者的計算方式
欄位 計算方式
minimum_bid_to_win
\(max\{F, W\}\)
sampled_mediation_cpm_ahead_
of_auction_winner
\(max\{X_1, …, X_K\}\)

簡單中介服務鏈的範例

假設發布商同時使用即時出價和 SDK 中介服務鏈，如下所示：

SDK 中介服務鏈 預期千次曝光出價 供應率
網路 1 \(C_1 = $3.00\) \(f_1 = 5\%\)
網路 2 \(C_2 = $2.00\) \(f_2 = 45\%\)
網路 3 \(C_3 = $0.50\) \(f_3 = 80\%\)
網路 4 \(C_4 = $0.10\) \(f_4 = 85\%\)

假設 RTB 競價結果如下：

即時出價競價 千次曝光出價
競價贏家 (W) $1.00 美元
競價第二名 (R) $0.05 美元
預留價格 / 底價 (F) $0
贏得競價的出價

以下範例說明系統如何計算得標出價的 minimum_bid_to_win 和 sampled_mediation_cpm_ahead_of_auction_winner 值與機率。

minimum_bid_to_win 機率
\(max(F, R, C_3) = $0.50\) \(f_3 = 80\%\)
\(max(F, R, C_4) = $0.10\) \((1-f_3) \cdot f_4 = 17\%\)
\(max(F, R, 0) = $0.05\) \((1-f_3) \cdot (1-f_4) = 3\%\)
sampled_mediation_cpm_
ahead_of_auction_winner		 機率
\(C_1 = $3.00\) \(f_1 \div (1-(1-f_1) \cdot (1-f_2)) =~ 10.5\%\)
\(C_2 = $2.00\) \(((1-f_1) \cdot f_2) \div (1-(1-f_1) \cdot (1-f_2)) =~ 89.5\%\)
未贏得競價的出價

以下範例說明系統如何計算出價遭拒時的 minimum_bid_to_win 和 sampled_mediation_cpm_ahead_of_auction_winner 值和機率。

minimum_bid_to_win 機率
\(max(F, W) = $1.00\) \(100\%\)
sampled_mediation_cpm_
ahead_of_auction_winner		 機率
\(C_1 = $3.00\) \(f_1 = 5\%\)
\(C_2 = $2.00\) \((1-f_1) \cdot f_2 =~ 42.8\%\)
\(0\) \((1-f_1) \cdot (1-f_2) =~ 52.2\%\)

分割出價

出價扁平化是指將單一複雜的 BidRequest 處理成多個出價要求，並傳送至應用程式。出價要求經過扁平化處理後，您就能判斷哪些出價要求屬於原始要求，因為這些要求在 BidRequest.ext.google_query_id 欄位中會有相同的值。

系統預設會啟用出價分割功能，但如果您想停用，請與客戶經理聯絡。

廣告格式

部分廣告機會可接受多種格式。出價分割後，每種格式都會透過不同的出價要求傳送，而符合資格的帳單 ID 等屬性，則與要求中指定的格式相關。

如果出價要求包含下列格式，系統會分割為不同的出價要求：

  • 橫幅廣告
  • 影片
  • 音訊
  • 原生

廣告格式扁平化範例

以下範例顯示簡化的 OpenRTB JSON 出價要求 (未經過廣告格式分割)，以及一組等效的分割要求：

Pre-flatten

Post-flatten

特惠

特定出價者的廣告商機可能適用於各種交易類型，公開競價也不例外。使用交易分割出價功能時，系統會為公開競價傳送一個出價要求，並為每種固定價格交易傳送一個出價要求。實務上，廣告限制可能因競價和固定價格交易類型而異。舉例來說，如果某個影片廣告商機同時適用於公開競價和固定價格交易，出價者會收到兩份不同的出價要求，其中廣告長度上限和是否允許可略過廣告等限制可能有所不同。因此，套用至廣告商機的平坦化功能可讓您更輕鬆地辨別開放競價和固定價格交易的廣告限制。

可略過性與影片長度

OpenRTB 規格沒有個別欄位，可指定可略過和不可略過廣告的影片長度上限。Google 的導入方式會使用出價平緩化，透過現有的 BidRequest.video.maxduration 和 BidRequest.video.skip 欄位區分這些事件。

以下範例說明當不可略過廣告長度上限為 15，可略過廣告長度上限為 60 時，影片廣告空間會如何扁平化。

範例 max_ad_duration skip (true OR false)
未經過扁平化的原始要求 15 true
分割式要求 #1：不可略過 15 false
分割式要求 #2：可略過 60 true

只有在符合下列條件時，系統才會分割可略過影片長度的出價要求：

  • 要求允許影片。
  • 可略過和不可略過的影片都可使用，但兩者的長度上限不同。
  • 這項請求符合私下競價或公開競價的資格。

如要停用這類分割出價功能，請與技術客戶經理聯絡。如果停用這項設定，且發布商允許可略過和不可略過影片廣告，並根據可略過性設定不同的廣告長度上限，則 skip 會設為 true，而 maxduration 會設為可略過和不可略過廣告限制中較短的時間長度。

影片廣告連播

如果影片廣告連播有多個廣告商機，出價要求就會分割，因此每個出價要求都只會對應連播中的個別廣告商機。這樣一來，您就能針對特定廣告連播中的多個廣告機會出價。

Open Measurement

您可以透過 Open Measurement 指定第三方供應商，為在行動應用程式環境中放送的廣告提供獨立的評估和驗證服務。

如要判斷發布商是否支援公開測量，請檢查廣告商機是否排除發布商可排除的廣告素材屬性中的 OmsdkType: OMSDK 1.0 屬性。這會顯示在「橫幅」或「影片」的 battr 屬性下方，視格式而定。

如要進一步瞭解如何解讀含有 Open Measurement 信號的出價要求，請參閱這篇說明中心文章。

出價要求範例

下列各節顯示不同廣告類型的範例出價要求。

應用程式橫幅廣告

OpenRTB Protobuf

OpenRTB JSON

應用程式插頁式廣告

OpenRTB Protobuf

OpenRTB JSON

應用程式插頁式影片

OpenRTB Protobuf

OpenRTB JSON

應用程式原生

OpenRTB Protobuf

OpenRTB JSON

網路影片

OpenRTB Protobuf

OpenRTB JSON

供交易平台出價者使用的行動版網站橫幅廣告

OpenRTB Protobuf

OpenRTB JSON

多格式原生和影片

OpenRTB Protobuf

OpenRTB JSON