處理要求

當 Google 傳送出價要求到您的應用程式時，即時出價互動隨即啟動。本指南說明如何為應用程式編寫程式碼，以處理出價要求。

剖析要求

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

您必須將此要求剖析為 BidRequest 訊息的執行個體。BidRequest 定義於 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++ 中：

for (int i = 0; i < bid_request.adslot_size(); ++i) {
  const BidRequest_AdSlot& adslot = bid_request.adslot(i);
  // Decide what to bid on adslot.
}

在 BidRequest 中傳送的部分資訊不一定隨時可用，例如 Google User ID、語言或地理位置。如果您有 預先指定廣告群組使用特定曝光時未知的資訊，這些廣告群組就會不相符。如果預先指定條件沒有遺漏的資訊，系統就會傳送出價要求，但省略其中的資訊。

與預先指定廣告群組有關的資訊，可在每個 AdSlot 的 MatchingAdData 群組中取得。其中包含了預先指定廣告群組的第一個相符廣告群組 ID，提示 Google 送出出價要求；也就是當您的回應贏得曝光競價時，須支付的廣告群組和廣告活動費用。在某些情況下，您必須在 BidResponse.AdSlot 中明確指定歸因的 billing_id，例如當 BidRequest.AdSlot 有多個 matching_ad_data 時。如要進一步瞭解出價內容的限制，請參閱 realtime-bidding.proto。

字典檔案

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

出價網址巨集

您可以選擇將 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 應用程式的應用程式 ID iFunny。

我們再看另一個例子回報的網址為： 

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

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

以下是取得應用程式名稱的範例。回報的網址如下： 

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 審查並參與 Authorized Buyers 互動的供應商。

如要瞭解 BidRequest 並建立 BidResponse，您必須瞭解兩種宣告技術供應商的不同可能性：

  1. 有些供應商不需要宣告；這些供應商已列在 Authorized Buyers 說明中。
  2. 其他供應商則必須同時在 BidRequest 和 BidResponse 中宣告，才能參與計畫：
    • 在 BidRequest 中，allowed_vendor_type 欄位會指定賣方允許哪些供應商。將在 BidRequest 的 allowed_vendor_type 欄位中傳送的供應商列於 Vendors.txt 字典檔案中。
    • 在 BidResponse 中，vendor_type 欄位會指定買方打算使用哪些已允許的供應商。

出價要求範例

下列範例是使用者可理解的 Protobuf 和 JSON 要求範例。

Google

OpenRTB JSON

OpenRTB 通訊協定緩衝區

如要將出價要求轉換為二進位格式，就像在實際要求中透過 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 會在來自行動應用程式的出價要求中傳遞行動廣告 ID。行動廣告 ID 可以是 iOS 廣告識別碼或 Android 廣告 ID，在 Authorized Buyers 管理的 JavaScript 代碼中，透過 %%EXTRA_TAG_DATA%% 巨集傳送。

%%ADVERTISING_IDENTIFIER%% 巨集可讓買方在顯示曝光時接收 iOS 廣告識別碼或 Android 的廣告 ID。此方法會傳回已加密的 proto 緩衝區 MobileAdvertisingId，例如 %%EXTRA_TAG_DATA%%：

message MobileAdvertisingId {
  optional bytes advertising_id = 1;
  optional int32 user_id_type = 2;
}

user_id_type 是 enum AdxMobileIdType 中定義的其中一個值：

enum AdxMobileIdType {
  MOBILE_ID_UNKNOWN = 0,
  IDFA = 1,
  ANDROID_ID = 2,
};

您可以使用在曝光顯示期間收集到的廣告 ID，透過行動廣告 ID 建立使用者名單。這些使用者名單可在您的伺服器 或我們的伺服器上維護如要在 Google 伺服器上建立使用者名單，您可以使用我們的大量上傳功能。

如果行動廣告 ID 符合使用者名單，您就可以使用這份 ID 執行再行銷。

即時意見回饋

Authorized Buyers、使用公開出價的廣告交易平台和聯播網皆可取得即時意見回饋。

針對 AdX Protocol 和 OpenRTB 的後續出價要求，出價回應意見回饋皆支援。如果是 OpenRTB，此訊息會在 BidRequestExt 中傳送。

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

當 Authorized Buyers 向出價方傳送出價要求時，出價方會以 BidResponse 回覆。如果出價工具啟用了即時意見回饋，則在後續的出價要求中，Authorized Buyers 會在 BidResponseFeedback 訊息中的回應傳送意見回饋，如下所示：

message BidResponseFeedback {
  // The unique id from BidRequest.id
  optional bytes request_id = 1;

  // The index of the BidResponse_Ad if there was more than one. The index
  // starts at zero for the first creative.
  optional int32 creative_index = 2;

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

  // 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 int64 cpm_micros = 4;

  // The minimum bid value necessary to have won the auction, in micros of
  // 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 did not 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 int64 minimum_bid_to_win = 7;

  // 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 micros 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 BidResponseFeedback object.
  optional int64 server_side_component_minimum_bid_to_win = 16;

  // 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 = 15 [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 micros of your account currency.
  optional int64 sampled_mediation_cpm_ahead_of_auction_winner = 10;

  // Event notification token that was included in the bid response.
  optional bytes event_notification_token = 5;

  // Buyer creative ID that was included in the bid response.
  optional string buyer_creative_id = 6;

  // 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 BidResponseFeedback message. Google will send separate
  // BidResponseFeedback 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 feedback_type = 17;

  // 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 buyer_origin = 18;

  // 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 interest_group_buyer_status_code = 19;
}

在這個訊息中，應檢查的第一個欄位為 bid_response_feedback.creative_status_code；您可以在 creative-status-codes.txt 中找到此程式碼代表的意義。請注意，如果您贏得出價，可以選擇退出價格回饋功能。詳情請參閱如何選擇退出。

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

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

針對應用程式曝光和 83 的廣告素材狀態碼，應用程式發布者可能會使用中介服務刊登序列，因此勝出的出價會與發布商的回傳式曝光刊登序列鏈中的其他需求競爭。瞭解如何在出價時使用 sampled_mediation_cpm_ahead_of_auction_winner。

範例

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

Google

OpenRTB JSON

OpenRTB 通訊協定緩衝區

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

在最高價得標競價中設定出價後，如果出價未從競價中篩除，您會收到即時意見回饋，包括 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\%\)

假設即時出價競價的結果如下：

即時出價競價 千次曝光出價
競價勝出者 (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 處理成傳送至您應用程式的多個出價要求。由於這些 ID 會保留相同的 ID (Authorized Buyers RTB 通訊協定中的 BidRequest.google_query_id，或 OpenRTB 通訊協定中的 BidRequestExt.google_query_id)，因此您可以決定在分割後，哪些出價要求具有關聯性。

廣告格式

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

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

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

廣告格式分割範例

以下範例顯示經過簡化的 OpenRTB JSON 出價要求，且未採用廣告格式分割，並比較一組對等的簡化請求：

預先壓層

柔化後

特惠

除了公開競價，特定出價方的廣告機會也適用於各種交易類型。使用交易分割出價時，系統會針對公開競價傳送一個出價要求，並為每種固定價格交易的類型分別發出一個出價要求。實務上，競價和固定價格交易類型的廣告限制可能不同。舉例來說，對於同時可供公開競價和固定價格交易的特定影片廣告商機，出價工具會收到不同的出價要求，其中每項限制 (例如廣告長度上限和是否允許可略過廣告) 可能各不相同。因此，對廣告機會進行分割，可讓您更輕鬆地區分公開競價和固定價格交易的廣告限制。

可略過的影片播放時間上限

對於影片時間長度和可略過性而言，Google 的通訊協定和 OpenRTB 實作支援下列欄位：

時間長度 可略過時間長度 可略過設定
Google 通訊協定 max_ad_duration skippable_max_ad_duration video_ad_skippable
OpenRTB maxduration n/a 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 (是或否)
未分割的原始要求 15 true
分割式請求 #1：不可略過 15 false
分割式請求 #2：可略過 60 true

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

  • 這項要求允許播放影片。
  • 可以略過和略過影片，且兩個時間長度上限的值各不相同。
  • 這項要求符合私下競價或公開競價資格。
  • 出價方帳戶具有有效的 OpenRTB 端點。

如要停用這類分割功能，請與客戶技術顧問聯絡。

影片廣告連播

如果影片廣告連播有多個廣告商機，出價要求會分割，因此每個出價要求都是針對該廣告連播中的個別廣告機會。您可以針對特定廣告連播，對多個廣告商機出價。

Open Measurement

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

您可以檢查廣告商機是否排除發布商可排除的廣告素材屬性中的 OmsdkType: OMSDK 1.0 屬性，以判斷發布商是否在出價要求中支援 Open Measurement。如果是 Authorized Buyers 通訊協定，則位於 BidRequest.adslot[].excluded_attribute 底下。如為 OpenRTB 通訊協定，可在橫幅或影片的 battr 屬性中找到這項資訊 (視格式而定)。

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

出價要求範例

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

應用程式橫幅廣告

Google

OpenRTB JSON

OpenRTB 通訊協定緩衝區

應用程式插頁式廣告

Google

OpenRTB JSON

OpenRTB 通訊協定緩衝區

應用程式插頁式影片廣告

Google

OpenRTB 通訊協定緩衝區

應用程式原生

Google

OpenRTB JSON

OpenRTB 通訊協定緩衝區

網路影片

Google

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

OpenRTB 通訊協定緩衝區