レスポンスの作成

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

BidResponse メッセージを作成します

認定バイヤーは、BidRequest を HTTP POST のメッセージ本文として送信します。アプリケーションから送信するレスポンスでは、Content-Type ヘッダーを application/octet-stream に設定し、メッセージ本文がシリアル化されたプロトコル バッファで構成されている必要があります。プロトコル バッファは、realtime-bidding.proto で定義されている BidResponse メッセージです。アプリケーションは、すべての BidRequest に対して解析可能な BidResponse を返す必要があります。解析できないタイムアウトとレスポンスはエラーと見なされ、Google はエラー率が高いビッダーを抑制します。

インプレッションへの入札を行わない場合は、processing_time_ms フィールドのみを設定し、他のフィールドはすべて空白のままにします。realtime-bidding.proto は、参照データページから取得できます。

クリエイティブ ID

BidResponse では、buyer_creative_id フィールドでクリエイティブを指定します(上限は 64 バイト)。類似のクリエイティブであっても、サイズ、宣言した URL、クリエイティブ属性、ベンダータイプなど、重要な特性が異なる場合は、buyer_creative_id に一意の値を設定する必要があります。つまり、次の 2 つの広告では、それぞれ別のクリエイティブ ID を付与する必要があります。

  • 外観や動作が異なる。
  • 異なる画像にレンダリングする。
  • レンダリング方法が異なります(たとえば、1 つの広告は画像で構成され、もう 1 つの広告は Flash で構成されます)。

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

広告の帰属表示

広告の特性とターゲティングを完全に説明するクリエイティブ属性を BidResponse.Ad.attribute で宣言する必要があります。宣言する必要がある属性は次のとおりです(サポートされている属性の一覧については、buyer-declarable-creative-attributes.txt をご覧ください)。

  • 7 Tagging: IsTagged
    広告にはピクセルやウェブビーコンが含まれており、リマーケティングに使用する Cookie ID のリストを作成するためのものです。
  • 8 Remarketing: IsRemarketing
    この広告では、Cookie ID またはデバイス ID に基づいて消費者がターゲティングされています。Cookie ID またはデバイス ID のリストは、購入者が所有または代表するサイトとやりとりしたことがある一連のユーザーを表します。
  • 9 UserInterestTargeting: IsUserInterestTargeted
    広告は、Cookie ID またはデバイス ID に基づいて消費者をターゲティングします。Cookie ID またはデバイス ID のリストは、購入者が共通のインタレスト グループとして定義した消費者のセットを表します。
  • 30 InstreamVastVideoType: Vpaid
    広告をレンダリングするには、VPAID のサポートが必要です。
  • 32 MraidType: MRAID
    広告を表示するには MRAID API が必要です。

また、次の属性もサポートされていますが、宣言は必須ではありません。認定バイヤーでは属性が自動的に検出され、宣言された値に基づいて、検出された値に基づいてクリエイティブがブロックされる(または許可される)ためです。 クリエイティブの検出されたプロパティに関するフィードバックを取得する方法については、Creatives API をご覧ください。

  • 34 RichMediaCapabilityType: RichMediaCapabilityFlash
    広告をレンダリングするには Flash サポートが必要です。
  • 50 RichMediaCapabilityType: RichMediaCapabilityNonFlash
    広告のレンダリングに Flash は不要です。
  • 47 RichMediaCapabilityType: RichMediaCapabilitySSL
    広告は SSL ページにレンダリングされます。認定バイヤーでは、この属性の宣言値が異なるクリエイティブをそれぞれ異なるクリエイティブとして扱います(個別の審査を受け、個別の承認ステータスを持ちます)。したがって、同じクリエイティブの SSL バージョンと非 SSL バージョンの両方を使って入札する場合は、この属性を適切に宣言して、この区別が AdX に適切に反映されるようにしてください。

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 秒以上に設定します。値が大きいほど、たいていの場合に役立ちます。Google では、アプリケーションの初期レイテンシ テストで検証を行います。これは、認定バイヤーがリクエストを高い頻度で送信し、リクエストごとに個別の TCP 接続を確立する際のレイテンシのオーバーヘッドを回避する必要があるためです。
  • 省略可能なインプレッション トラッキング URL を含めて、ビッダーが落札したときではなく、インプレッションがレンダリングされたときをトラッキングします。勝利とレンダリングの間にドロップが生じるため、より正確な追跡統計が得られます。

  • ビッダーのコードでは、サポートが終了したフィールドへの依存を避ける必要があります。サポートが終了したフィールドがあると、エラーによって入札が失敗する可能性があります。
  • BidResponseBidResponse.Ad.widthBidResponse.Ad.height を含めます。複数の広告サイズを含むリクエストに対する BidResponse には、widthheight の値を含める必要があります。この値がないと、オークションから除外されます。
  • レスポンスのサイズは 8K 未満にしてください。レスポンスが非常に大きいと、ネットワーク レイテンシが増加し、タイムアウトが発生する可能性があります。
  • SKAdNetwork アトリビューションが必要な iOS 広告枠への入札に関するガイドラインを遵守します。

入札レスポンスの例

次の例は、人間が読める形式の Protobuf と JSON のリクエストのサンプルを示しています。

Google

OpenRTB JSON

OpenRTB プロトコル

重要: サンプルに示されている 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.Ad.sdk_rendered_ad
  • AMP
    • BidResponse.Ad.amp_ad_url
  • 動画
    • BidResponse.Ad.video_url または
    • BidResponse.Ad.video_vast_xml
  • ネイティブ
    • BidResponse.Ad.native_ad

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

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

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

html_snippet フィールドは、正しくレンダリングされる有効な HTML コードをすべてサポートしますが、BidResponse メッセージの作成セクションで buyer_creative_id フィールドを指定する際の制限に注意してください。用途の 1 つは、広告をレンダリングする際に、サーバーから取得した URL の引数に情報を追加することです。これにより、インプレッションに関する任意のデータを独自のサーバーに返すことができます。

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

マクロを指定する

クリエイティブを定義する HTML スニペットには、マクロと呼ばれる特別な構造を 1 つ以上含めることができます。広告配信時には、値がマクロに代入されます。たとえば、クライアント入札のアプリケーションで WINNING_PRICE マクロを使用すると、オークションで落札した場合に広告への支払い額を確認できます。このマクロを解析するには、価格確認を復号するアプリケーションを実装する必要があります。詳しくは、料金の確認の復号のページをご覧ください。

マクロを HTML スニペットの一部として %%MACRO%% の形式で指定します。MACRO は、以下の表に示すサポートされているマクロのいずれかです。

Google では、第三者配信のクリエイティブのクリエイティブ内で CLICK_URL_UNESC または CLICK_URL_ESC マクロを使用することを義務付けています。Google はクリック トラッキングに CLICK_URL マクロを使用しています。

マクロを使用するには、URL が広告に含まれていれば、誰かがクリックしたときに取得されるように、広告にマクロを含めます。取得の戻り値は、CLICK_URL に追加する別の URL へのリダイレクトです。

マクロ 説明
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 パラメータのエスケープを解除することを前提としています。

ダブルエスケープの URL は、%%CLICK_URL_ESC%% の後に追加できます。my.adserver.com によってエスケープ解除が完了すると、URL のシングル エスケープ バージョンが google_click_url に追加されます。google_click_url をフェッチすると、エスケープ解除が再度行われ、リダイレクトされます。

CLICK_URL_ESC_ESC

広告のダブルエスケープ URL。最初に別のサーバー経由で値を渡してからリダイレクトを返す必要がある場合は、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)。つまり、アカウントの通貨はマイクロ単位です。たとえば、5 米ドルの落札 CPM は 5,000,000 マイクロ CPM または 5,000 マイクロ CPI に相当します。この場合、デコードされた WINNING_PRICE の値は 5,000 になります。落札価格は CPI で指定します。
WINNING_PRICE_ESC URL エスケープされた WINNING_PRICE

マクロで URL をエスケープするには、次のスキームを使用します。

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

パブリッシャー向け制限コンテンツ

パブリッシャーは BidRequest を使用して、許可する広告の制限を渡すことができます。次のフィールドに制限を適用する必要があります。

  • allowed_vendor_type
  • excluded_attribute
  • excluded_sensitive_category

1 つは広告の許可された機能を指定し、もう 1 つは禁止される機能を指定します。許可されていない機能を含む広告は返さないようにしてください。ベンダー タイプなどの許可された機能については、ベンダータイプが BidRequestallowed_vendor_type リストにある場合にのみ、広告を返します。詳細については、BidRequest プロトコル バッファ定義のこれらのフィールドのコメントをご覧ください。

BidResponse で HTML スニペットが返される場合は、BidResponseattributecategoryclick_through_url の各フィールドを正確に設定する必要があります。これらのフィールドに該当する値が複数ある場合は、すべての値を含める必要があります。詳細については、BidResponse プロトコル バッファ定義のこれらのフィールドのコメントをご覧ください。これらのフィールドが設定されていないレスポンスは破棄されます。

BidRequest.excluded_attribute の有効な値は次のとおりです(publisher-excludable-creative-attributes.txt を参照)。

  • 7 Tagging: IsTagged
    その後のマーケティングのために Cookie ID のリストを作成する目的でピクセルまたはウェブビーコンが含まれている場合は、広告は許可されません。
  • 8 CookieTargeting: IsCookieTargeted
    Cookie ID に基づいて消費者をターゲットに設定している場合、こうした広告は許可されません。その場合、Cookie ID のリストは、購入者が所有または代表するサイトを利用したことがある一連のユーザーを表すものです。
  • 9 UserInterestTargeting: IsUserInterestTargeted
    Cookie ID に基づいて消費者をターゲットとする場合、広告は許可されません。その場合、Cookie ID のリストは、購入者が共通のインタレスト グループとして定義した一連のユーザーを表します。
  • 21 CreativeType: Html
    BidResponse.Ad では html_snippetsnippet_template フィールドを使用できません。
  • 22 CreativeType: VastVideo
    BidResponse.Advideo_url フィールドを使用することは許可されていません。
  • 30 InstreamVastVideoType: Vpaid
    広告を VPAID サポートでレンダリングすることは許可されていません。
  • 32 MraidType: MRAID
    MRAID API を表示するために広告を使用することはできません。
  • 34 RichMediaCapabilityType: RichMediaCapabilityFlash
    広告をレンダリングするために Flash サポートを必須にすることはできません。
  • 39 RichMediaCapabilityType: RichMediaCapabilityHTML5
    広告の HTML5 機能の表示を広告に許可することはできません。
  • 48 RichMediaCapabilityType: RichMediaCapabilityNonSSL
    広告で SSL 以外のリクエストを送信することはできません。

したがって、excluded_attribute フィールドに値 7 が含まれている場合、ピクセルまたはウェブビーコンを使用してリストを作成する広告は返すべきではありません。この場合は、BidResponse の属性フィールドに値 7 を設定する必要があります。 同様に、excluded_attribute フィールドに値 48 が含まれている場合、SSL ページにレンダリングできる広告のみを返す必要があります(それにより、属性 47 の RichMediaCapabilityType: RichMediaCapabilitySSL が宣言されます)。

また、BidRequestexcluded_sensitive_category フィールドには、参照データページにある ad-sensitive-categories.txt ファイルのコードが使用されます。以下に、これらのコードの一部について詳しく説明します。

  • 3 Politics
    政治的または物議を醸す社会問題が含まれます。一般的に問題に対する党派的な見解とは無関係な報道機関の広告は対象外です。
  • 4 Dating
    出会い系サービスやオンラインの出会い系コミュニティが含まれます。
  • 5 Religion
    宗教的な広告や、宗教に関する賛成または反対の見解を宣伝する広告が該当します。星占いや、特定の教派に偏らない宗教的な内容は含まれません。
  • 7 Video Games (Casual & Online)
    ビデオゲーム、オンライン ゲーム、ダウンロード可能なゲームが含まれます。ビデオゲーム本体に関する広告は含まれません。
  • 8 Ringtones & Downloadables
    着信音などのモバイル アドオンのほか、デスクトップ PC でのスクリーンセーバーや壁紙、ソーシャル ネットワーク向けのプロフィールのレイアウトやグラフィックスなど、ダウンロード可能なアイテムも含まれます。
  • 10 Get Rich Quick
    迅速な収益を期待するスキーム。
  • 18 Weight Loss
    減量、ダイエットに関連する商品やプログラムの広告が含まれます。健康的な食事や一般的な健康法に関する広告は含まれません。
  • 19 Cosmetic Procedures & Body Modification
    フェイスリフト、脂肪吸引、レーザー施術、脱毛、植毛、タトゥー、美容形成などが含まれます。
  • 23 Drugs & Supplements:
    医薬品、ビタミン剤、サプリメント、それらに関連した販売店の広告。薬物に関する情報を提供するリソースは含まれません。
  • 24 Sexual & Reproductive Health
    性機能や不妊対策に関する広告が含まれます。通常の妊娠に関するリソースは含まれません。
  • 35 Social Casino Games
    価値のあるもの(金銭や商品など)を獲得できないギャンブルのシミュレーション ゲーム(ポーカー、スロット、ビンゴ、宝くじ、スポーツ賭博、レースに対する賭け、その他のカードゲームやカジノゲームなど)。
  • 36 Significant Skin Exposure
    胸から太ももまでで一部の肌が露出している人物の広告画像。または、下着、水着、その他の肌が透けて見える衣服、あるいはタオル、シーツなど衣服以外のものを身に着けている人物の広告画像。
  • 37 Sensationalism
    好奇心をあおってクリックするように仕向ける広告で、多くの場合は大げさな表現や派手な画像を使った表面的なメッセージが使われます。刺激的なテーマ(有名人の逮捕や訃報、離婚など)に焦点を当てた広告や、衝撃を与えることを狙った広告が該当します

測定を開く

Open Measurement を使うと、モバイルアプリ環境に配信される広告について、独立した測定と検証のサービスを提供する第三者ベンダーを指定できます。

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

入札レスポンスの例

次のセクションでは、広告タイプごとの入札レスポンスの例を紹介します。

アプリバナー

Google

OpenRTB JSON

OpenRTB プロトコル

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

Google

OpenRTB JSON

OpenRTB プロトコル

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

Google

OpenRTB JSON

OpenRTB プロトコル

アプリ ネイティブ

Google

OpenRTB JSON

OpenRTB プロトコル

ウェブ動画

Google

OpenRTB JSON

OpenRTB プロトコル

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

OpenRTB プロトコル