處理要求

當 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，這些 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 的應用程式 ID。

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

mbappgewtgmjug4ytmmrtgm888888.com
 解碼這個值： 
GEWTGMJUG4YTMMRTGM======
 會產生以下結果： 
1-314716233
 結果 314716233 是 iOS 應用程式 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 審查通過的供應商才能參與授權買方互動。

如要瞭解 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，或是與廣告素材相關聯的 metadata (只有出價方知道)。詳情請參閱 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;

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

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

在最高價得標競價中出價後，如果出價未從競價中篩除，您會收到即時意見回饋，包括 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 出價要求 (不含廣告格式扁平化)，以及等同的扁平化要求：

預先扁平化

平坦化後

特惠

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

可略過性和影片長度

OpenRTB 規格沒有專屬欄位，可用來指定可略過和不可略過影片廣告的時間長度上限。Google 的導入方式會使用出價平坦化功能，透過現有的 BidRequest.video.maxduration 和 BidRequest.video.skip 欄位來區分這些欄位。

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

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

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

  • 這項要求允許使用影片。
  • 可略過和不可略過的影片都適用此設定，且兩者的廣告長度上限值不同。
  • 這項要求符合私下競價或公開競價的資格。

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

影片廣告連播

針對含有多個廣告商機的影片廣告連播，系統會將出價要求分割，讓每個出價要求都對應到該廣告連播中的個別廣告商機。這樣一來，您就能針對特定連播出價多個廣告商機。

Open Measurement

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

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

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

出價要求範例

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

應用程式橫幅廣告

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