リクエストを処理する

リアルタイム入札のインタラクションは、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

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

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

辞書ファイル

入札リクエストでは、ディクショナリ ファイルで定義された ID が使用されます。これらの ID は、参照データページで入手できます。

ビッダーの URL マクロ

必要に応じて、BidRequest の一部の情報は、マクロを使用して入札エンドポイントの URL に挿入できます。1 つ以上のマクロを使用してエンドポイント URL を構成すると、その情報が入札リクエストに存在する場合、マクロが展開されます。これは、BidRequest の情報に基づいてロード バランシングを実行する場合などに便利です。新しいマクロのサポートをリクエストするには、アカウント マネージャーにお問い合わせください。

マクロ説明
%%GOOGLE_USER_ID%%

BidRequest.user.id にある Google ユーザー 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%%

入札リクエストがモバイル デバイスからのものであることを示す 1 に置き換えられます。それ以外の場合は 0 に置き換えられます。これは BidRequest.device.devicetype の値に基づいています。モバイル デバイスは HIGHEND_PHONE（4）または Tablet（5）で示されます。
%%HAS_VIDEO%%

入札リクエストに動画広告枠が含まれていることを示す 1 に置き換えられました。含まれていない場合は 0 です。これは、入札リクエストに BidRequest.imp.video が入力されているかどうかに基づきます。
%%HOSTED_MATCH_DATA%%

BidRequest.user.buyeruid に基づく値に置き換えられました。
%%MOBILE_IS_APP%%

入札リクエストがモバイルアプリ広告枠を対象としている場合は 1 に置き換え、それ以外の場合は 0 に置き換えられます。これは、BidRequest.app に値が入力されているかどうかに基づいています。

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

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

mbappgewtimrzgyytanjyg4888888.com

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

オンライン デコーダを使用できますが、文字を大文字に変更し、末尾の 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

パブリッシャーのアド マネージャー ネットワーク コードと、スラッシュで区切った広告ユニット階層が含まれます。

たとえば、/1234/cruises/mars のような書式になります。
BidRequest.user.data.segment

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

BidRequest.user.data.name が “Publisher Passed” に設定されている場合、値はパブリッシャーから送信された Key-Value ペアであると判断できます。

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

リサーチ、リマーケティング、広告配信などのサービスを提供する技術事業者は、購入者と販売者のやり取りに役割を果たす場合があります。認定バイヤーとのやり取りに参加するために 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

実際のリクエストの 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 を使用しているエクスチェンジとネットワークで利用できます。

リアルタイム フィードバックでは、以前に行われた 1 つ以上の入札の結果に基づいて BidRequest.ext.bid_feedback が入力されます。これを使用して、入札がオークションで落札されたかどうか、オークションで落札するために必要な最小入札単価などの詳細を確認できます。リアルタイム フィードバックを有効にするには、アカウント マネージャーにお問い合わせください。

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

認定バイヤーがビッダーに入札リクエストを送信すると、ビッダーは 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;

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

  // 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 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 の有効な値を決定するために使用される計算を説明するには、まず次のことを定義する必要があります。

  • メディエーション チェーンの 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\%\)

入札リクエストの分割

入札フラット化とは、単一の複雑な BidRequest を複数の入札リクエストに処理してアプリケーションに送信することを指します。入札リクエストがフラット化されると、BidRequest.ext.google_query_id フィールドの値が同じになるため、元の入札リクエストの一部だった入札リクエストを特定できます。

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

広告フォーマット

一部の広告掲載オプションでは、複数のフォーマットを使用できます。入札のフラット化では、各フォーマットが個別の入札リクエストで送信されます。この場合、対象の請求 ID などの属性は、リクエストで指定されたフォーマットに関連付けられます。

次のフォーマットを含む入札リクエストは、個別の入札リクエストに分割されます。

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

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

以下に、広告フォーマットのフラット化を行わない簡素化された OpenRTB JSON 入札リクエストと、同等のフラット化されたリクエストのセットを示します。

事前フラット化

フラット化後

特価

特定のビッダーの広告機会は、公開オークションに加えて、さまざまな取引タイプに適用できます。取引の入札リクエストの分割では、公開オークション用に 1 件、固定価格取引のタイプごとに 1 件の入札リクエストが送信されます。実際には、オークションと固定価格取引の種類によって広告の制約が異なる場合があります。たとえば、オープンオークションと固定価格取引の両方で利用可能な特定の動画広告オポチュニティの場合、入札者はそれぞれ異なる入札リクエストを受信します。広告の最大再生時間やスキップ可能な広告の許可など、制約が異なる場合があります。広告オポチュニティにフラット化を適用すると、オープン オークションと固定価格取引の広告制約をより簡単に把握できます。

スキップ設定と動画の長さ

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