處理要求

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

剖析 Protobuf 要求

Google 會將出價要求做為序列化的通訊協定緩衝區傳送，並附加為 HTTP POST 要求的二進位酬載。Content-Type 設為 application/octet-stream。如需範例，請參閱出價要求範例。

您必須將這項要求解析為 BidRequest 訊息的例項。視所選通訊協定而定，BidRequest 會在 openrtb.proto 或已淘汰的 realtime-bidding.proto 中定義，您可以從參考資料頁面取得這些資訊。您可以使用 BidRequest 產生的類別中的 ParseFromString() 方法剖析訊息。舉例來說，下列 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，這些 ID 可在「參照資料」頁面中找到。

Google RTB 通訊協定出價網址巨集

您可以選擇將 BidRequest 的部分欄位插入 HTTP POST 要求中使用的網址。舉例來說，如果您使用輕量前端，並透過要求中的值在多個後端之間進行負載平衡，這項功能就很實用。請與技術客戶經理聯絡，要求支援新巨集。

巨集說明
%%GOOGLE_USER_ID%%

已由 BidRequest 中的 google_user_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%%

呼叫 BidRequest 的 has_mobile() 時，會以 1 或 0 取代。
%%HAS_VIDEO%%

呼叫 BidRequest 的 has_video() 時，會以 1 (true) 或 0 (false) 取代。
%%HOSTED_MATCH_DATA%%

替換為 BidRequest 的 hosted_match_data 欄位值。
%%MOBILE_IS_APP%%

由 BidRequest 的 mobile.is_app 欄位替換為 1 (true) 或 0 (false)。

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

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

mbappgewtimrzgyytanjyg4888888.com

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

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

因此，請解碼這個值：

GEWTIMRZGYYTANJYG4======
 會產生以下結果： 
1-429610587
 字串 429610587 是 iOS 應用程式 iFunny 的應用程式 ID。

以下再舉一例。回報的網址如下： 

mbappgewtgmjug4ytmmrtgm888888.com
 解碼這個值： 
GEWTGMJUG4YTMMRTGM======
 會產生以下結果： 
1-314716233
 結果 314716233 是 iOS 應用程式 TextNow 的應用程式 ID。

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

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

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

公開出價欄位

傳送至參與公開出價的廣告交易平台和聯播網出價方，與參與標準即時出價的 Authorized Buyers 類似。公開出價客戶將收到少數額外欄位，且部分現有欄位可能有其他用途。其中包括：

OpenRTB Authorized Buyers 詳細資料
BidRequest.imp[].ext.dfp_ad_unit_code BidRequest.adslot[].dfp_ad_unit_code

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

舉例來說，格式會類似於：/1234/cruises/mars。
BidRequest.user.data[].segment[] BidRequest.adslot[].exchange_bidding.key_value[]

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

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

宣告允許的供應商

提供研究、再行銷和廣告放送等服務的技術供應商，可能會在買方和賣方之間的互動中扮演角色。只有 Google 審查通過的供應商才能參與授權買方互動。

如要瞭解 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

Google (已淘汰)

如要將出價要求轉換為二進位檔案，就像從實際要求中的 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 也能取得即時意見回饋。

後續出價要求 (OpenRTB 和已淘汰的 Google RTB 通訊協定) 都支援出價回應意見回饋。對於 OpenRTB，則會透過 BidRequest.ext.bid_feedback 傳送。

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

當 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;

  // The minimum bid value necessary to have won the server-side component of
  // the overall auction given that there was also an interest group bidding
  // component to the overall auction which ran using the Protected Audience
  // API. The value is expressed in CPM of the buyer account currency. The
  // minimum bid to win for the overall auction, including bids from the
  // server-side and the on-device interest group components, is populated in
  // the minimum_bid_to_win field of the same BidFeedback object.
  optional double sscminbidtowin = 14;

  // 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;

  // Possible types of bid response feedback objects.
  enum FeedbackType {
    FEEDBACK_TYPE_UNSPECIFIED = 0;

    // Feedback for a bid that was submitted on a bid response.
    BID_FEEDBACK = 1;

    // Feedback for an interest group buyer submitted on a bid response to
    // particpate in an interest group bidding component of the auction run
    // using the Protected Audience API.
    INTEREST_GROUP_BUYER_FEEDBACK = 2;
  }

  // The type of the BidFeedback message. Google will send separate
  // BidFeedback objects for:
  // a) Each bid submitted on a bid response
  // b) Each buyer submitted on a bid response to particpate in an interest
  // group bidding component of the auction run using the Protected Audience
  // API.
  optional FeedbackType feedbacktype = 15;

  // Origin of an interest group buyer that was included in the bid response.
  // This field is populated only for feedback where a bidder opted in an
  // interest group buyer to participate in the interest group bidding
  // component of the overall auction run using the Protected Audience API.
  // To learn more about origins, see https://www.rfc-editor.org/rfc/rfc6454.
  // To learn more about interest group bidding and the Protected Audience
  // API, see
  // https://developers.google.com/authorized-buyers/rtb/fledge-origin-trial.
  optional string buyerorigin = 16;

  // The status code for the submitted interest group buyer. This field is
  // only populated in the feedback for an interest group buyer that a bidder
  // requested to enter into the interest group auction through the bid
  // response. Individual creative status codes of bids submitted by the buyer
  // in the on-device interest group auction are not available. See
  // https://storage.googleapis.com/adx-rtb-dictionaries/interest-group-buyer-status-codes.txt
  // for a list of interest group buyer status codes.
  optional int32 igbuyerstatus = 17;
}

根據這則訊息，您應該檢查的第一個欄位是 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

Google (已淘汰)

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

在最高價得標競價中出價後，如果系統未從競價中篩除出價，您就會收到即時意見回饋，包括 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\]
  • 以下是仲介鏈結中 CPM 的對應填充率：
    \[f_1, f_2, …, f_n\]
  • 以下是函式，可根據指定的填充率，從中介鏈元素 \(i\)判斷預期千次曝光出價及其機率：
    \(X_i = \{C_i\) with probability \(f_i\); \(0\) with probability \(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\) with probability \(\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 出價要求，不含廣告格式扁平化，並與等同的扁平化要求進行比較：

預先扁平化

平坦化後

交易

除了公開競價外，特定出價方適用的廣告放送機會也適用於各種交易類型。啟用交易的分割出價功能後，系統會為公開競價傳送一個出價要求，並為每種固定價格交易類型傳送一個出價要求。實際上，廣告限制可能因競價和固定價格交易類型而異。舉例來說，如果某個影片廣告機會同時適用於公開競價和固定價格交易，出價方會收到各自的出價要求，其中的限制條件 (例如廣告長度上限和是否允許可略過廣告) 可能會有所不同。因此，將平坦化套用至廣告商機，即可更輕鬆地判斷公開競價和固定價格交易的廣告限制。

可略過影片時間長度上限

Google 的通訊協定和 OpenRTB 實作項目支援下列影片片長和可略過欄位：

時間長度 可略過的時間長度 可略過
Google 通訊協定 max_ad_duration skippable_max_ad_duration video_ad_skippable
OpenRTB maxduration 不適用 skip

也就是說，雖然 Google 通訊協定可提供可略過和不可略過的細微時間長度，但 OpenRTB 實作僅有單一最大時間長度值。

在將出價扁平化之前，OpenRTB 的 maxduration 會設為 Google 通訊協定的 max_ad_duration 和 skippable_max_ad_duration 欄位中較低的值。這項行為現在已改為在這些值不同時傳送兩個個別出價要求：一個代表可略過的 maxduration，另一個代表不可略過的機會。

以下範例說明 Google 通訊協定要求在出價扁平化前後如何轉譯為 OpenRTB。等效的 Google 通訊協定要求具有 15 的 max_ad_duration，以及 60 的 skippable_max_ad_duration。

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

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

  • 這項要求允許使用影片。
  • 可略過和不可略過的影片都適用此設定，且兩者的時間長度上限不同。
  • 這項要求符合私下競價或公開競價的資格。
  • 出價方帳戶有有效的 OpenRTB 端點。

如要停用這類分割出價，請與技術客戶經理聯絡。

影片廣告連播

包含多個廣告商機的影片廣告連播，其出價要求會分割，每個出價要求都會針對該廣告連播中的個別廣告商機。這樣一來，您就能針對特定連播出價多個廣告放送機會。

Open Measurement

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

如要判斷發布商是否支援出價要求中的公開評估功能，請檢查廣告機會是否排除發布商可排除的廣告素材屬性中的 OmsdkType: OMSDK 1.0 屬性。這項資訊會顯示在 battr 屬性 (橫幅或影片) 下方，具體取決於格式。

如要進一步瞭解如何解讀含有公開評估信號的出價要求，請參閱「公開評估 SDK」說明中心文章。

出價要求範例

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

應用程式橫幅廣告

OpenRTB Protobuf

OpenRTB JSON

Google (已淘汰)

應用程式插頁式廣告

OpenRTB Protobuf

OpenRTB JSON

Google (已淘汰)

應用程式插頁式影片

OpenRTB Protobuf

OpenRTB JSON

Google (已淘汰)

原生應用程式

OpenRTB Protobuf

OpenRTB JSON

Google (已淘汰)

網路影片

OpenRTB Protobuf

OpenRTB JSON

Google (已淘汰)

廣告交易平台出價方適用的行動版網站橫幅廣告

OpenRTB Protobuf

OpenRTB JSON

多格式原生和影片

OpenRTB Protobuf

OpenRTB JSON

Google (已淘汰)