處理要求

當 Google 傳送出價要求給 應用程式本指南說明如何編寫應用程式的程式碼 處理出價要求

剖析 Protobuf 要求

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

您必須將這項要求剖析為 BidRequest 的例項 撰寫新的電子郵件訊息視所選協定而定，BidRequest 會在 openrtb.proto 或已淘汰的 realtime-bidding.proto 中定義，您可以從「參考資料」頁面取得這些資料。您可剖析訊息 將 ParseFromString() 方法用於 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 預先指定設定此外，如果是 特惠 廣告空間，您可以查看與相關買方相關聯的帳單 ID 使用 BidRequest.imp.pmp.deal.ext.billing_id。出價時，只能指定出價要求中包含的買方帳單 ID。

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

字典檔案

出價要求會使用在字典檔案中定義的 ID， 參考資料中會提供 頁面。

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

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

巨集說明
%%GOOGLE_USER_ID%%

已替換為 google_user_id 來自 BidRequest。例如：出價工具網址 

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的has_mobile()。
%%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 審查的供應商才能參與授權買方互動。

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

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

  // The minimum bid value necessary to have 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 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 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：如有 中介服務鏈中的其他聯播網 這個欄位的值即為價格，代表了其中一個 符合資格且高於競價勝出者的中介服務聯播網，加權 根據預期供應率如果 Pod 中沒有任何網路 中介服務鏈預計會供應廣告，或如果發布商未使用 SDK 中介服務。

運作方式

說明用於決定可能值的計算結果 適用於 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\) 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 指定第三方供應商，為放送至行動應用程式環境的廣告提供獨立評估和驗證服務。

您可以判斷發布商是否支援出價中的 Open Measurement 方法是檢查廣告商機是否排除「發布商可排除」中的 OmsdkType: OMSDK 1.0 屬性。 廣告素材屬性，這項資訊會顯示在 battr 屬性 (橫幅或影片) 下方，具體取決於格式。

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

出價要求範例

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

應用程式橫幅廣告

OpenRTB Protobuf

OpenRTB JSON

Google (已淘汰)

應用程式插頁式廣告

OpenRTB Protobuf

OpenRTB JSON

Google (已淘汰)

應用程式插頁式影片

OpenRTB 通訊協定緩衝區

Google (已淘汰)

原生應用程式

OpenRTB 通訊協定緩衝區

OpenRTB JSON

Google (已淘汰)

網路影片

Google (已淘汰)

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

OpenRTB Protobuf