リクエストを処理する

リアルタイム入札のやり取りは、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 を取得したら、オブジェクトとして操作し、必要なフィールドを抽出して解釈できます。たとえば、 OpenRTB の「BidRequest」で取引を反復処理する C++ は、次のようになります。 次のとおりです。

for (const BidRequest::Imp::Pmp::Deal& deal : pmp.deals()) {
  DoSomething(deal.id(), deal.wseat());
}

請求 ID

入札リクエストは、パブリッシャーの広告枠がターゲットに 1 つ以上の プレターゲティング設定をご覧ください。BidRequest.imp.ext.billing_id 対象となる購入者の請求 ID が入力され、関連する プレターゲティング設定を指定しますまた お得 広告在庫では、関連する購入者に関連付けられた請求 ID を確認できます BidRequest.imp.pmp.deal.ext.billing_id を使用します。入札時に指定できるのは、入札リクエストに含まれる購入者の請求 ID のみです。

入札リクエストに複数の請求 ID が含まれている場合は、入札を関連付ける購入者の請求 ID を BidResponse.seatbid.bid.ext.billing_id フィールドで指定する必要があります。

辞書ファイル

入札リクエストでは、辞書ファイルで定義された識別子が使用されます。 （参照データを参照） できます。

Google RTB プロトコルの入札 URL マクロ

必要に応じて、BidRequest のいくつかのフィールドを HTTP POST リクエストで使用される URL。これは、たとえば、kubectl の ロード バランシングを行う軽量のフロントエンドで、 取得されます。テクニカル アカウント マネージャーに連絡して、 作成します。

マクロ説明
%%GOOGLE_USER_ID%%

BidRequest の google_user_id に置き換えられました。たとえば、ビッダー URL

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）に置き換えられます。

取引 URL からモバイルアプリ ID を確認する

モバイル アプリケーションのトランザクションでは、次のような URL が報告されます。

mbappgewtimrzgyytanjyg4888888.com

ベース 32 デコーダを使用して、太字の文字列部分（gewtimrzgyytanjyg4888888）をデコードします。

オンライン decoder になりますが、文字を大文字にし、末尾を = 値を持つ 8。

したがって、この値

GEWTIMRZGYYTANJYG4======
をデコードすると、
1-429610587
になります。文字列 429610587 は、iOS アプリ iFunny のアプリ ID です。

別の例を次に示します。報告された URL は次のとおりです。 

mbappgewtgmjug4ytmmrtgm888888.com
この値をデコードすると、次のようになります。 
GEWTGMJUG4YTMMRTGM======
1-314716233
結果の 314716233 は、iOS アプリ TextNow のアプリ ID です。

取引の URL からモバイルアプリの名前を確認する

アプリ名を取得する例を次に示します。報告された URL は次のとおりです。 

mbappMFUXELTDN5WS42DZOBQWQLTJN4XHG3DJORUGK4Q888.com
この値をデコードすると、次のようになります。 
MFUXELTDN5WS42DZOBQWQLTJN4XHG3DJORUGK4Q===
air.com.hypah.io.slither
この結果は、Android アプリ slither.io と同じです。

Open Bidding のフィールド

Open Bidding に参加しているエクスチェンジとネットワークのビッダーに送信される入札リクエストは、標準のリアルタイム ビッダーに参加している認定バイヤーの入札リクエストと類似しています。Open Bidding をご利用のお客様には、いくつかのフィールドが追加され、既存のフィールドの一部は別の用途に使用できるようになります。たとえば、次のようなものです。

OpenRTB 認定バイヤー 詳細
BidRequest.imp[].ext.dfp_ad_unit_code BidRequest.adslot[].dfp_ad_unit_code

パブリッシャーのアド マネージャー ネットワーク コードの後に広告が続きます 単位階層構造をスラッシュで区切って示しています

たとえば、次のような形式で表示されます。 /1234/cruises/mars。
BidRequest.user.data[].segment[] BidRequest.adslot[].exchange_bidding.key_value[]

パブリッシャーからエクスチェンジ入札者に送信される Key-Value ペアの重複。

値は、ファイアウォール ルールによって BidRequest.user.data[].name が次の値に設定されている場合のパブリッシャー “Publisher Passed”。

許可するベンダーを宣言する

リサーチ、リマーケティング、広告配信などのサービスを提供する技術事業者は、購入者と販売者のやり取りに役割を果たす場合があります。認定バイヤーとのやり取りに参加するために Google が審査したベンダーのみが許可されます。

BidRequest を理解して BidResponse を作成するには、技術ベンダーを宣言する 2 つの方法を把握する必要があります。

  1. 宣言が不要なベンダーもあります。これらのベンダーは アド マネージャー認定外部向け ベンダー。
  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
  }
}

リアルタイムのフィードバック

リアルタイムのフィードバックは、認定バイヤー、および Open Bidding を使用しているエクスチェンジとネットワークが利用できます。

入札レスポンス フィードバックは、OpenRTB と非推奨の Google RTB プロトコルの両方で、後続の入札リクエストでサポートされています。OpenRTB の場合は BidRequest.ext.bid_feedback で送信されます。

入札レスポンス フィードバックで送信されるデフォルト フィールドに加えて、BidResponse.seatbid.bid.ext.event_notification_token フィールドを使用して入札レスポンスでカスタムデータを送信することもできます。「 event_notification_token は、 デバッグに役立つビッダー（新しいターゲティング ID や 新しい戦術を表す入札 ID、またはクリエイティブに関連付けられたメタデータ ビッダーにのみ通知されます。詳しくは、OpenRTB の OpenRTB Extensions Protocol Buffer または非推奨の Google RTB プロトコルをご覧ください。

<ph type="x-smartling-placeholder">

認定バイヤーからビッダーに入札リクエストが送信されると、ビッダーは BidResponse に置き換えます。ビッダーでリアルタイム フィードバックが有効になっている場合は、 後続の入札リクエストで認定バイヤーから 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 とクリエイティブのステータス コード 1。

アプリ インプレッションでクリエイティブのステータス コードが 83 の場合、 アプリ パブリッシャーがメディエーション ウォーターフォールを使用していた可能性があるため、 落札した入札がパブリッシャーの パスバック ウォーターフォール チェーンです。使用方法を見る 次の場合: sampled_mediation_cpm_ahead_of_auction_winner 入札。

サンプル

以下は、サポートされているリアルタイムのフィードバックの例です。 機能:

OpenRTB プロトコル バッファ

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: メディエーション チェーンの他のネットワーク、 このフィールドの値は、 オークションの落札者よりも高かった、条件を満たすメディエーション ネットワーク（重み付けあり） 推定広告掲載率で入札しますメディエーション チェーン内のネットワークがいずれもフィードを提供することが想定されない場合、またはパブリッシャーが SDK メディエーションを使用していない場合、この値は 0 に設定されます。

仕組み

minimum_bid_to_win と sampled_mediation_cpm_ahead_of_auction_winner の有効な値を決定するために使用される計算を説明するには、まず次のことを定義する必要があります。

  • 以下は、メディエーション チェーンの CPM を降順で表したものです。
    \[C_1, C_2, …, C_n\]
  • 各キャンペーンの CPM の広告掲載率は、以下のようになります。 メディエーション チェーン:
    \[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 メディエーション チェーン 推定 CPM 広告掲載率
ネットワーク 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 オークション CPM
オークション落札者（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\%\)

入札単価のフラット化

入札単価のフラット化は、1 つの 複数の入札リクエストに対してBidRequestを 説明します。入札リクエストがフラット化されると、BidRequest.ext.google_query_id フィールドの値が同じになるため、元の入札リクエストの一部だった入札リクエストを特定できます。

入札単価の分割はデフォルトで有効になっていますが、無効にしたい場合はアカウント マネージャーにお問い合わせください。

広告フォーマット

一部の広告掲載オプションでは、複数のフォーマットを使用できます。入札単価のフラット化では という形式が個別の入札リクエストで送信されます。その場合は、 請求 ID は、リクエストで指定された形式に関連しています。

次のフォーマットを含む入札リクエストは、 利用できるので、

  • バナー
  • 動画
  • 音声
  • ネイティブ

広告フォーマットのフラット化の例

以下は、広告なしの簡略化した OpenRTB JSON 入札リクエストの例です。 フラット化されたリクエストの同等のセットと比較した場合のフォーマットのフラット化:

事前にフラット化

フラット化後

特価

特定のビッダーの広告オポチュニティは、公開オークションに加えて、さまざまな取引タイプに適用できます。取引のフラット化では 固定価格のタイプごとに 1 つずつ、 あります実際のところ、広告の制約はオークションと固定価格とで異なる場合があります。 取引タイプ（たとえば特定の動画広告オポチュニティの 公開オークションと固定料金取引の両方の 入札が同じ場合 広告の最大再生時間、広告の最大再生時間、 異なる場合があります広告オポチュニティにフラット化を適用すると、オープン オークションと固定価格取引の広告制約をより簡単に把握できます。

スキップ可能な動画の最大再生時間

Google のプロトコルと OpenRTB の実装でサポートされるフィールドは次のとおりです。 （動画の再生時間とスキップの可否）:

所要時間 スキップ可能な動画の再生時間 スキップ可能かどうか
Google プロトコル max_ad_duration skippable_max_ad_duration video_ad_skippable
OpenRTB maxduration なし skip

つまり、Google プロトコルではスキップ可能時間とスキップ不可時間の詳細を指定できますが、OpenRTB 実装では最大時間の値を 1 つだけ指定できます。

入札単価のフラット化が行われる前は、OpenRTB の maxduration は次のように設定されています。 Google プロトコルの max_ad_duration と skippable_max_ad_duration フィールド。この動作は、これらの値が異なる場合に 2 つの個別の入札リクエストを送信するように変更されました。1 つはスキップ可能な広告の maxduration を表し、もう 1 つはスキップ不可の広告の機会を表します。

次の例は、Google プロトコル リクエストが OpenRTB への入札のフラット化の前後に行われます。同等の Google プロトコル リクエストの max_ad_duration は 15、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 属性が除外されているかどうかを確認します。これは、フォーマットによって、バナーまたは動画の battr 属性で確認できます。

Open Measurement シグナルを含む入札リクエストを解釈する方法について詳しくは、Open Measurement SDK のヘルプセンター記事をご覧ください。

入札リクエストの例

以下のセクションでは、広告タイプ別の入札リクエストの例を示します。

アプリバナー

OpenRTB Protobuf

OpenRTB JSON

Google（非推奨）

アプリ インタースティシャル

OpenRTB Protobuf

OpenRTB JSON

Google（非推奨）

アプリ インタースティシャル動画

OpenRTB Protobuf

Google（非推奨）

アプリのネイティブ

OpenRTB Protobuf

OpenRTB JSON

Google（非推奨）

ウェブ動画

Google（非推奨）

エクスチェンジ入札者向けのモバイルウェブバナー

OpenRTB プロトコル バッファ