レスポンスを作成する

アプリケーションは、Google からの入札リクエストを処理した後、レスポンスを作成して送信する必要があります。このガイドでは、レスポンスの作成を目的としたアプリケーションのコードについて説明します。

Protobuf BidResponse メッセージを作成する

認定バイヤーは、HTTP POST のメッセージ本文として BidRequest を送信します。入札エンドポイントが Protobuf 形式を使用するように構成されている場合、アプリケーションは、Content-Type ヘッダーを application/octet-stream に設定し、シリアル化されたプロトコル バッファで構成されるメッセージ本文を含むレスポンスを送信する必要があります。プロトコル バッファは、openrtb.proto で定義されている BidResponse メッセージです。アプリは、すべての BidRequest に対して解析可能な BidResponse を返す必要があります。タイムアウトや解析できないレスポンスはエラーと見なされ、エラー率が高いビッダーはスロットリングされます。

インプレッションに入札しない場合は、空の HTTP 204 レスポンスを返す必要があります。openrtb.proto は、参照データページから取得できます。

クリエイティブ ID

BidResponse では、BidResponse.seatbid.bid.crid フィールドを使用してクリエイティブを指定します(64 バイト上限)。サイズ、申告された URL、クリエイティブ属性、ベンダータイプなど、顕著な特性が異なる場合は、類似のクリエイティブでも、このフィールドに一意の値を指定する必要があります(ただしこれらに限定されません)。つまり、次の条件を満たす 2 つの広告には、異なるクリエイティブ ID を割り当てる必要があります。

  • 外観や動作が異なる。
  • 別の画像にレンダリングする。
  • 異なる方法でレンダリングする(1 つの広告が画像で構成され、もう 1 つが動画であるなど)。

アプリケーションを設計する際は、送信するクリエイティブの種類に適した識別子を生成する体系的な方法を決定する必要があります。

広告の帰属表示

BidResponse.seatbid.bid.apisBidResponse.seatbid.bid.attr の組み合わせ、または BidResponse.seatbid.bid.ext.attribute 拡張機能を使用してクリエイティブ属性を宣言し、広告の特性とターゲティングを記述することをおすすめします。属性を宣言する方法は次のとおりです。

  • VPAID
    BidResponse.seatbid.bid.apisVPAID_1 または VPAID_2 に設定します。JSON 形式の場合は、それぞれ 1 または 2 に設定できます。
  • MRAID
    BidResponse.seatbid.bid.apisMRAID_1 に設定します。JSON 形式の場合は 3 に設定します。
  • SIZELESS
    BidResponse.seatbid.bid.attrRESPONSIVE に設定します。JSON 形式の場合は 18 に設定します。
  • PLAYABLE
    これは、BidResponse.seatbid.bid.attrUSER_INTERACTIVE に設定するか、JSON 形式の場合は 13 に設定することで示されます。

クリエイティブで検出されたプロパティに関するフィードバックを取得する方法については、クリエイティブ リソースをご覧ください。

Open Bidding のフィールド

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

OpenRTB 認定バイヤー 詳細
BidResponse.imp[].pmp.deals[].id BidResponse.ad[].adslot[].exchange_deal_id

この入札に関連付けられ、パブリッシャーに報告されるエクスチェンジの名前空間の取引 ID。

BidResponse.seatbid[].bid[].ext.exchange_deal_type BidResponse.ad[].adslot[].exchange_deal_type

パブリッシャーに報告される取引のタイプ。オークションでの取引の処理方法に影響します。

BidResponse.seatbid[].bid[].ext.third_party_buyer_token BidResponse.ad[].adslot[].third_party_buyer_token Open Bidding ユーザーとしてエクスチェンジが仲介者である場合に、最終的な第三者購入者情報を識別するために使用されるトークン。これはサードパーティの購入者から取得され、入札レスポンスで変更せずに Google に渡す必要があります。

推奨事項

  • サーバーで永続的な HTTPS 接続(「キープアライブ」または「接続の再利用」とも呼ばれる)を有効にします。タイムアウトは少なくとも 10 秒に設定します。多くの場合、値を大きくすると効果的です。Authorizes Buyers はリクエストを高速で送信するため、リクエストごとに個別の TCP 接続を確立するレイテンシのオーバーヘッドを回避する必要があります。そのため、Google はアプリケーションの最初のレイテンシ テストでこのことを確認します。
  • 入札者が落札したときではなく、インプレッションがレンダリングされたときをトラッキングするには、オプションのインプレッション トラッキング URL を含めます。勝利とレンダリングの間に減少があるため、より正確なトラッキング統計情報が得られます。

  • 入札コードで非推奨のフィールドに依存しないようにしてください。依存すると、入札が失敗してエラーが発生する可能性があります。
  • BidResponseBidResponse.seatbid.bid.wBidResponse.seatbid.bid.h を含めます。複数の広告サイズを含むリクエストの BidResponse には、これらのフィールドを含める必要があります。含めないと、オークションから除外されます。
  • レスポンス サイズは 8,000 バイト未満に制限してください。非常に大きなレスポンスがあると、ネットワーク レイテンシが増加し、タイムアウトが発生する可能性があります。
  • SKAdNetwork アトリビューションを必要とする iOS 広告枠への入札に関するガイドラインに沿って対応してください。

入札レスポンスの例

次の例は、Protobuf リクエストと JSON リクエストの読み取り可能なサンプルを示しています。

OpenRTB Protobuf

OpenRTB JSON

Google

重要: サンプルに示されている Protobuf メッセージは、人間が読み取り可能なテキストとしてここに示されています。ただし、これはワイヤーを介してメッセージを送信する方法ではありません。Google または OpenRTB Protobuf 形式を使用する場合は、シリアル化された BidResponse メッセージのみが受け入れられます。

次の C++ コードを使用して、BidResponse メッセージを作成してシリアル化できます。

BidResponse bid_response;
// fill in bid response with bid information
string post_response;
if (bid_response.SerializeToString(&post_response)) {
  // respond to the POST with post_response as the content
} else {
  // return an error to the POST
}

クリエイティブを指定する

入札レスポンスでは、入札が落札した場合に配信するクリエイティブを指定します。入札には、サポートされている広告フォーマット(AMP、動画、ネイティブ)のいずれかを含める必要があります。この例では、html_snippet フィールドを使用してクリエイティブを指定します。

または、広告フォーマットに基づいて、次のフィールドのいずれかを使用してクリエイティブを指定することもできます。

  • SDK レンダリング広告
    • BidResponse.seatbid.bid.ext.sdk_rendered_ad
  • AMP
    • BidResponse.seatbid.bid.amp_ad_url
  • 動画
    • BidResponse.seatbid.bid.adm
  • ネイティブ
    • BidResponse.seatbid.bid.adm_native

BidResponse.seatbid.bid.adm フィールドで HTML スニペットを使用して、独自のサーバーでホストされている広告を指定します。スニペットはウェブページに挿入された iframe 内に囲まれているため、ページが読み込まれると広告が取得され、レンダリングされます。広告(バナーまたはインタースティシャル)が iframe 内で正しくレンダリングされ、入札する広告スロットに適したサイズになるように、HTML スニペットを作成する必要があります。

また、次の場合に、入札レスポンスで宣言された広告サイズは、入札リクエストのサイズの組み合わせの 1 つと完全に一致している必要があります。

  • 広告が通常のバナーである(動画、ネイティブ、インタースティシャルではない)。
  • ビッダーが入札レスポンスでサイズを宣言している。リクエストに複数のサイズが存在する場合は、サイズの宣言が必要です。
  • インタースティシャル広告は例外です。インタースティシャルの場合は、幅が画面幅の 50% 以上、高さが画面高さの 40% 以上である必要があります。

適切にレンダリングされる有効な HTML コードを使用して HTML スニペット クリエイティブを指定できますが、Create BidResponse メッセージを作成するセクションで crid フィールドを指定する際の制限事項に注意してください。たとえば、広告のレンダリングの一環としてサーバーから取得される URL の引数に追加情報を追加できます。これにより、インプレッションに関する任意のデータを独自のサーバーに渡すことができます。

入札レスポンスで返される HTML スニペットのポリシーのほとんどは、サードパーティ広告の場合と同じです。詳しくは、認定購入者プログラム ガイドライン第三者配信に関する要件広告でクリックスルー URL を宣言するをご覧ください。

マクロを指定する

マクロは、URL を含む一部の入札レスポンス フィールドに埋め込まれたフォーマット済みテキストで、広告配信時に関連する値に置き換えられます。たとえば、落札した入札に含まれる HTML スニペット クリエイティブに AUCTION_PRICE マクロが含まれている場合、そのマクロは復号可能な値に置き換えられ、オークションでインプレッションに対して支払った金額を特定できます。

マクロは次のフィールドに含めることができます。

  • BidResponse.seatbid.bid.adm

    マクロは、HTML スニペット、ネイティブ、動画 URL、動画 VAST XML の各形式でサポートされています。

  • BidResponse.seatbid.bid.adm_native.eventtrackers.url

  • BidResponse.seatbid.bid.adm_native.imptrackers

  • BidResponse.seatbid.bid.ext.amp_ad_url

    AMP クリエイティブでは、Google 固有の WINNING_PRICE マクロと WINNING_PRICE_ESC マクロのみがサポートされています。

  • BidResponse.seatbid.bid.burl

  • BidResponse.seatbid.bid.ext.impression_tracking_url

    複数の請求 URL が必要な場合は、BidResponse.seatbid.bid.burl の代わりにこれを使用します。

たとえば、クリエイティブの取得に使用する URL 内に ${MACRO} を埋め込むことで、HTML スニペットの一部としてマクロを含めることができます。ここで、MACROOpenRTB 仕様で説明されているサポートされているマクロの 1 つです。

Google RTB マクロ

Google は、OpenRTB 仕様にあるマクロ以外にも、追加のマクロをサポートしています。これらのマクロの形式は異なり、URL に埋め込まれると %%MACRO%% と表示されます。次の表に、これらのマクロについて説明します。

マクロ 説明
ADVERTISING_IDENTIFIER 購入者がインプレッションのレンダリング時に iOS の IDFA または Android の広告 ID を受け取ることを許可します。詳しくは、広告主 ID の復号をご覧ください。
CACHEBUSTER ランダムな 4 バイト符号なし整数の文字列表現。
CLICK_URL_UNESC

エスケープ処理なしの広告のクリック URL。スニペットでは、エスケープ処理された第三者のクリック URL をこのマクロの直後に記述する必要があります。

たとえば、第三者のクリック URL が http://my.adserver.com/some/path/handleclick?click=clk の場合、マクロ呼び出しの後に単一エスケープされたバージョンの第三者のクリック URL を使用して、次のコードを使用できます。

<a href="%%CLICK_URL_UNESC%%http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a>

広告配信時に、次のように展開されます。

<a href="http://google-click-url?...&ad_url=http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a>

この URL は、まず Google にクリックを登録し、次にサードパーティのクリック URL にリダイレクトします。

CLICK_URL_ESC

エスケープ処理された広告のクリック URL。まず別のサーバーに値を渡し、そのサーバーからリダイレクトを返すようにする場合は、CLICK_URL_UNESC の代わりにこのマクロを使用します。

たとえば、HTML スニペットで次のコードを使用できます。

<a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%"></a>

広告配信時に、次のように展開されます。

<a href="http://my.adserver.com/click?google_click_url=http://google-click- url%3F...%26ad_url%3D"></a>

これにより、my.adserver.com にクリックが登録され、google_click_url パラメータで渡された URL へのリダイレクトが実行されます。これは、my.adserver.comgoogle_click_url パラメータをエスケープすることを前提としています。

%%CLICK_URL_ESC%% の後に、二重エスケープされた URL を追加できます。my.adserver.com によってエスケープ解除が完了すると、google_click_url に URL の単一エスケープ バージョンが追加されます。google_click_url がフェッチされると、もう一度エスケープされてからリダイレクトされます。

CLICK_URL_ESC_ESC

広告の URL を 2 回エスケープしたものです。まず別のサーバーに値を渡し、そのサーバーからリダイレクトを返すようにする場合は、CLICK_URL_UNESC の代わりにこのマクロを使用します。

たとえば、HTML スニペットで次のコードを使用できます。

<a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC_ESC%%"></a>

広告配信時に、次のように展開されます。

<a href="http://my.otheradserver.com/click?google_click_url=http%3A%2F%2Fmy.adserver.com%2Fclick%3Fgoogle_click_url%3Dhttp%3A%2F%2Fgoogle-click-%20url%253F...%2526ad_url%253D"></a>
SCHEME 入札リクエストで SSL が不要な場合は http: に拡張され、入札リクエストで SSL が必要な場合は https: に拡張されます。
SITE コンテンツ URL の URL がエスケープされたドメイン、または匿名広告枠の匿名 ID。
SITE_URL 非推奨です。同じ機能を提供する SITE マクロに置き換えられました。
TZ_OFFSET タイムゾーンのオフセット。
VERIFICATION

本番環境と、検証パイプラインでクリエイティブがスキャンされる場合の値が異なります。形式は %%?VERIFICATION:true-val:false-val%% です。true-valfalse-val には、マクロを除く任意の値(空の文字列を含む)を使用できます。Open Bidding では、エクスチェンジでこのマクロを使用することをおすすめします。エクスチェンジでこのマクロを使用すると、デマンドサイド プラットフォームで変更する必要がなくなります。

たとえば、クリエイティブに %%?VERIFICATION:-1:5000%% が含まれている場合、テキスト置換は配信では 5000、検証パイプラインでは -1 になります。これは、この 2 つの ping セットを区別するのに役立ちます。

WINNING_PRICE

エンコードされたインプレッションの費用(CPM ではなく CPI)をアカウントの通貨で 100 万倍した値を返します。たとえば 5 米ドルの落札 CPM は、500 万マイクロ CPM または 5,000 マイクロ CPI に相当し、この場合、WINNING_PRICE をデコードした値は 5,000 になります。落札価格は CPI で表されます。

このマクロを解析するには、料金確認を復号するアプリケーションを実装する必要があります。詳細については、料金確認の復号のページをご覧ください。

WINNING_PRICE_ESC URL エスケープされた WINNING_PRICE

サードパーティが配信する広告のクリエイティブ内で、CLICK_URL_UNESC マクロまたは CLICK_URL_ESC マクロのいずれかを使用する必要があります。Google は、クリック トラッキングに CLICK_URL マクロを使用します。

マクロでの URL エスケープでは、次のスキームが使用されます。

  • スペース文字はプラス記号(+)に置き換えられます。
  • 英数字(0 ~ 9、a ~ z、A ~ Z)と、!()*、-./:_~ の文字は変更されません。
  • 他のすべての文字は %XX に置き換えられます。ここで、XX は文字を表す 16 進数です。

パブリッシャー向けの制限と要件

入札リクエストには、パブリッシャーがオークションのクリエイティブに適用する制限と要件の種類に関する情報が含まれます。

  • BidRequest.bcat
    • このフィールドで指定したブロックされたカテゴリと、Real-time Bidding API の detectedCategories フィールドで検出されたカテゴリを比較できます。
  • BidRequest.imp.ext.allowed_vendor_type
  • BidRequest.imp.secure
    • 実際には、すべてのクリエイティブで SSL サポートが必須であるため、この値は常に true に設定されます。
  • BidRequest.imp.{audio/banner/native/video}
  • BidRequest.imp.{audio/banner/native/video}.api
  • BidRequest.imp.{audio/banner/native/video}.battr
  • BidRequest.imp.{audio/banner/video}.mimes

制限付きの機能を含む広告で入札しないでください。ベンダータイプなどの許可された機能については、ベンダータイプが BidRequestallowed_vendor_type リストに含まれている場合にのみ、広告を返します。入札に含めることができるのは、BidRequest.imp.banner などのフィールドに値を入力して入札リクエストで指定した広告フォーマットのみです。詳細については、BidRequest プロトコル バッファ定義のこれらのフィールドのコメントをご覧ください。

BidResponse で広告が返された場合は、BidResponseBidResponse.seatbid.bid.attrBidResponse.seatbid.bid.catBidResponse.seatbid.bid.adomain または BidResponse.seatbid.bid.adm_native.link.url のいずれかのフィールドを正確に設定する必要があります。広告にこれらのフィールドに該当する値が複数ある場合は、すべての値を含める必要があります。詳細については、BidResponse プロトコル バッファ定義のこれらのフィールドのコメントをご覧ください。これらのフィールドが設定されていないレスポンスは破棄されます。

Open Measurement

Open Measurement では、モバイルアプリ環境に配信される広告の独立した測定と検証サービスを提供するサードパーティ ベンダーを指定できます。

サポートされている広告フォーマットは、動画広告、バナー広告、インタースティシャル広告です。これらのフォーマットを含む入札レスポンスで Open Measurement を使用する方法について詳しくは、Open Measurement SDK のヘルプセンター記事をご覧ください。

入札レスポンスの例

以降のセクションでは、さまざまな広告タイプの入札レスポンスの例を示します。

アプリバナー

OpenRTB Protobuf

OpenRTB JSON

Google

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

OpenRTB Protobuf

OpenRTB JSON

Google

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

OpenRTB Protobuf

OpenRTB JSON

Google

アプリのネイティブ

OpenRTB Protobuf

OpenRTB JSON

Google

ウェブ動画

OpenRTB Protobuf

OpenRTB JSON

Google

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

OpenRTB Protobuf

OpenRTB JSON