處理要求

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

剖析要求

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

您必須將這項要求剖析為 BidRequest 的例項 撰寫新的電子郵件訊息BidRequest 已在 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++：

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 使用者 不一定都能使用 ID、語言或地理位置。如果您是 使用未知資訊的預先指定廣告群組 那麼這些廣告群組就不會一致如果缺少 對預先指定條件來說並不重要，出價要求會 以遺漏資訊送出去

如要瞭解預先指定廣告群組的相關資訊，請前往 每個AdSlot的「MatchingAdData」群組。這個 SDK 包含 要求 Google 存取的預先指定廣告群組 ID 也就是付費的廣告群組和廣告活動 您的回應贏得了曝光競價低於確定度 但必須明確指定 billing_id BidResponse.AdSlot 中的歸因，例如當 BidRequest.AdSlot有多個matching_ad_data。 若要進一步瞭解出價內容的限制，請參閱 realtime-bidding.proto。

字典檔案

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

出價網址巨集

您可以視需要將 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%%

已替換為 1 (true) 或 0 (false) 呼叫 BidRequest 的 has_video() 時。
%%HOSTED_MATCH_DATA%%

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

已替換為 1 (true) 或 0 (false) 擷取自 BidRequest 的 mobile.is_app 欄位

從交易網址找出行動應用程式 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 可以是 iOS IDFA 或 Android 廣告 ID：透過 %%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 建立使用者名單 列出的 Cookie可維護這些使用者名單 伺服器或我們的主機代管如要在 Google 伺服器上建立使用者名單，您可以使用 以及大量上傳功能

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

即時意見回饋

所有 Authorized Buyers 都可查看即時意見回饋 視為採用公開出價的廣告交易平台和聯播網

出價回應意見回饋功能適用於 AdX 通訊協定和 OpenRTB。如果是 OpenRTB，會以 BidRequestExt。

除了出價回應意見回饋中傳送的預設欄位外，您還可以 也會在出價回應中傳送自訂資料 (在 AdX Proto 或 OpenRTB 中) 使用傳回的 event_notification_token， BidResponse。event_notification_token是 可協助偵錯的出價方取得任意資料 例如新的指定目標 ID 或出價 ID 代表新策略，或是 僅與出價方知道的廣告素材相關聯中繼資料。詳情 請參閱 OpenRTB 即時出價的擴充功能通訊協定緩衝區 和 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：如有 中介服務鏈中的其他聯播網 這個欄位的值即為價格，代表了其中一個 符合資格且高於競價勝出者的中介服務聯播網，加權 根據預期供應率如果 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\) 與機率 \(\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 (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 不適用 skip

這表示雖然 Google 通訊協定可以精細地略過 和不可略過的持續時間，使用 OpenRTB 時，只有單一 時間長度上限值。

在分割出價之前，OpenRTB 的 maxduration 會設為 Google 通訊協定的 max_ad_duration 和較低值 skippable_max_ad_duration 欄位。此行為現已變更為 當這些值不同時，就傳送兩個不同的出價要求：一個代表 maxduration：可略過 商機。

以下範例說明 Google 通訊協定要求如何轉譯 改為在分割出價前後開啟 OpenRTB。對等的 Google 通訊協定 要求含有 15 的 max_ad_duration，而 第 skippable_max_ad_duration 個，共 60 個。

範例 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 屬性。 廣告素材屬性，對於 Authorized Buyers 通訊協定，這會是 在 BidRequest.adslot[].excluded_attribute 下找到。對於 OpenRTB 通訊協定，位於 battr 屬性下方 適用於橫幅或 影片 (視情況而定) 格式。

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

出價要求範例

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

應用程式橫幅廣告

Google

OpenRTB JSON

OpenRTB 通訊協定緩衝區

應用程式插頁式廣告

Google

OpenRTB JSON

OpenRTB 通訊協定緩衝區

應用程式插頁式影片

Google

OpenRTB 通訊協定緩衝區

應用程式原生廣告

Google

OpenRTB JSON

OpenRTB 通訊協定緩衝區

網路影片

Google

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

OpenRTB 通訊協定緩衝區