處理要求

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

imp {
  ext {
    // The billing IDs of all of your matching pretargeting configs and eligible child seats are
    // stored in a flat list here.
    billing_id: 123
    billing_id: 456
    billing_id: 789
  }
  pmp {
    // All eligible deals are stored in a single flat list.
    deal {
      id: 1000
      ext {
        // The specific billing IDs eligible to bid on this deal are indicated here.
        billing_id: 789
      }
      ...
    }
    deal {
      id: 2000
      ext {
        billing_id: 123
        billing_id: 456
      }
      ...
    }
  }
  ...
}
...

判斷遭封鎖的類別

出價時，內含的廣告素材不得有發布商封鎖的偵測類別。否則出價會從競價中篩除。

如要查看曝光的封鎖類別，請檢查 BidRequest.bcat 欄位，其中會填入帳戶設定的分類類別。

以下範例顯示根據設定的廣告類別分類，封鎖的類別：

IAB 內容分類 1.0 版

// Bid request
{
  // Indicates the blocked categories using IAB Content 1.0 Taxonomy.
  "bcat": [
    "IAB9-9",  // Cigars
    "IAB8-18"  // Wine
  ]
  "imp": {
    ...
  }
}
      
// Bid request
{
  // Indicates the blocked categories using Google Ad Category Taxonomy.
  "bcat": [
    "10138",  // Cigar and tobacco collecting
    "10080",  // Tobacco
    "11649",  // Wine
    "10674",  // Wine collecting
    "13008"   // Wine clubs
  ]
  "imp": {
    ...
  }
}

判斷內容類別

出價要求可以包含內容比對類別欄位，說明顯示曝光的網站或應用程式。這些欄位同樣使用廣告類別分類，但代表的是曝光情境，而非廣告素材限制。這些欄位可能不會使用與 BidRequest.bcat 欄位相同的分類。Google 或發布商可提供這些內容相關類別。使用內容比對類別，可能有助於改善曝光評估、內容比對指定目標和品牌安全。

Google 偵測到的內容比對類別

Google 會在下列欄位填入偵測到的網站、應用程式或網頁 IAB 內容類別：

欄位 說明
BidRequest.site.cat 描述網站的內容類別 ID 陣列。
BidRequest.site.pagecat 描述網站目前網頁或檢視畫面的內容類別 ID 陣列。
BidRequest.app.cat 描述應用程式的內容類別 ID 陣列。
BidRequest.app.pagecat 內容類別 ID 陣列，說明應用程式的目前網頁或檢視畫面。

如要瞭解特定出價要求中這些欄位使用的確切分類，請參閱 BidRequest.site.cattax 或 BidRequest.app.cattax 欄位。由於發布商偏好設定或法規考量，情境類別欄位不一定會填入資料。詳情請參閱「Google Ad Manager 中的 OpenRTB 內容類別」。

發布商提供的信號

除了 Google 偵測到的內容比對類別外，出價要求也可能包含發布商提供的信號，這些信號也會描述曝光的內容。與 Google 偵測到的內容相關類別不同，只有在發布商提供時，系統才會填入這些信號。這些信號會透過 BidRequest.site.content 和 BidRequest.app.content 物件傳送，例如 content.data.segment 和 content.genre。content.data.segment 項目的分類會記錄在 content.data.ext.segtax 中。詳情請參閱「運用發布商提供的信號 (PPS) 進行即時出價 (RTB)」。

字典檔案

出價要求會使用字典檔案中定義的 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。
%%IS_CTV%%

改用 1 表示出價要求來自連網電視裝置，否則使用 0。這項指標是根據 BidRequest.device.devicetype 的值計算而來。如果是 Protobuf，連網電視裝置為 CONNECTED_TV、CONNECTED_DEVICE 或 SET_TOP_BOX，對應 JSON 的整數值 3、6 或 7。
%%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」iFunny的應用程式 ID。

讓我們再看一例。遭檢舉的網址為： 

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

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

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

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

公開出價欄位

傳送給參與公開出價的廣告交易平台和聯播網出價方的出價要求，與參與標準即時出價的授權買方類似。公開出價客戶會收到少量額外欄位，部分現有欄位可能有其他用途。其中包括：

OpenRTB 詳細資料
BidRequest.imp.ext.dfp_ad_unit_code

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

舉例來說，這會顯示為類似以下的格式：/1234/cruises/mars。
BidRequest.user.data.segment

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

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

聲明允許的供應商

提供研究、再行銷和廣告放送等服務的技術供應商，可能會在買賣雙方的互動中扮演重要角色。只有經 Google 審查、可參與 Authorized Buyers 互動的供應商，才能使用這項功能。

如要瞭解 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，或只有出價方知道的廣告素材相關中繼資料。詳情請參閱 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;

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

在這則訊息中，您應檢查的第一個欄位是 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\]
  • 以下代表中介服務鏈中千次曝光出價的相應填寫率：
    \[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\%\)

假設 RTB 競價結果如下：

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 可讓您指定第三方供應商，為在行動應用程式環境中放送的廣告，提供獨立評估和驗證服務。

如要判斷發布商是否支援出價要求中的 Open Measurement，請檢查廣告商機是否排除發布商可排除的廣告素材屬性中的 OmsdkType: OMSDK 1.0 屬性。這會顯示在「橫幅」或「影片」的 battr 屬性下方，視格式而定。

如要進一步瞭解如何解讀含有 Open Measurement 信號的出價要求，請參閱 Open Measurement 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