處理要求

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 的應用程式 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 欄位會指定賣家允許的供應商。vendors.txt 字典檔案中列出了將在 allowed_vendor_type 中傳送的供應商。

出價要求範例

以下是 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 屬性。視格式而定,這項資訊會顯示在「Banner」或「Video」的 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