Cookie マッチング

以下のトピックでは、単価設定の効率化を可能にする Cookie マッチング サービスについて説明します。

  1. Cookie マッチングの概要
  2. 予備知識
  3. ホスト型マッチ テーブルのメリット
  4. Cookie マッチングの仕組み
  5. Cookie マッチング サービスの使用方法
  6. ピクセル マッチング
  7. 制限事項
  8. API の仕様
  9. Cookie マッチング サービス API V1 からの移行
重要: ここでは Cookie マッチング サービス API の最新バージョンである V2 について説明します。アプリケーションで V1 を使用している場合は、V1 の仕様をご覧ください。

Cookie マッチングの概要

Cookie マッチング サービスを使用すると、次の 2 種類のデータを関連付けることができます。

  1. 購入者のドメイン内でユーザーを識別する Cookie
  2. Google のユーザーを識別する doubleclick.net Cookie(購入者がマッチングに使用できるよう、購入者専用に暗号化された Google ユーザー ID が提供されます)

購入者がこれらのデータの関連付けを維持するデータ構造をマッチ テーブルといいます。マッチ テーブルの作成と管理は購入者が行いますが、テーブルは Google でホスト可能です。

RTB アプリケーションを使用する購入者は、Google ユーザー ID を持つユーザーへのインプレッションで、その ID に関連付けられている情報を入札条件として使用できます。また、マッチ テーブルを Google でホストすれば、データの統合が簡単で待ち時間も減り、将来的な拡張も可能です。

トップへ戻る

予備知識

通常、ブラウザの Cookie は、その Cookie が帰属するドメインの所有者によって設定され、そのドメイン内のユーザーを識別するために使用されます。しかし、ブラウザのセキュリティ モデルでは、Cookie を設定した当事者以外がその Cookie を読み取ることが禁止されており、たとえ両者の間でそうした情報のやり取りについて合意が可能な場合でも認められません。

そこで、購入者は一般的に第三者広告ネットワークのドメインに帰属する Cookie でユーザーを識別し、これらの Cookie でインデックスを作ってユーザー情報のデータベースを作成します。

このため、Google が Google 自身のユーザーを識別する際には、広告配信を行う doubleclick.net ドメインに帰属する Cookie を使用しますが、Google が購入者のユーザーを識別する際には、購入者専用の Google ユーザー ID を使用します。この ID は doubleclick.net の Cookie を暗号化したもので、元は doubleclick.net の Cookie ですが同じものではありません。Google では、この Google ユーザー ID を購入者に渡します(元の DoubleClick Cookie が送られることはありません)。

購入者が初めての(それまで受け取ったことのない)Google ユーザー ID を受け取った場合、入札リクエストで把握できる情報を除き、その ID に関連付けられたユーザーの情報は何もありません。購入者は Google ユーザー ID と自身の Cookie を関連付けることで、それ以降にその ID で識別されるユーザーへのインプレッションに入札する際に、購入者 Cookie に関連付けられたユーザー情報を考慮して適切な判断ができるようになります。こうした手法は、リマーケティング キャンペーンを展開する場合や、リアルタイムで購入可能なインプレッションのターゲット設定や入札単価を調整する場合に役立ちます。

Cookie マッチング サービスでは、購入者の Cookie と Google ユーザー ID の関連付けを維持するために必要な情報が、マッチ テーブルと呼ばれるデータ構造で提供されます。また、今後の入札リクエストのために Google で保存、追加するデータを購入者が提供することもできます。

トップへ戻る

ホスト型マッチ テーブルのメリット

重要: このサービスをご希望の場合は、アカウント担当者までご連絡ください。

購入者がマッチ テーブルのホストを Google に任せると、次のようなメリットがあります。

  • サポートするインフラが少なくて済む
  • Google ユーザー ID が便利な形式でマッピングされるため、ルックアップ テーブルが不要になる
  • プレターゲティングの段階で、Cookie マッチの有無に応じてフィルタをかけるオプションがあるため、不要な入札リクエストを削減できる

トップへ戻る

Cookie マッチングの仕組み

マッチ テーブルで関連付けを行う購入者は、Google が提供する「マッチ タグ」というタグを配信する必要があります。マッチ タグは、購入者の広告と一緒に配信するか、広告以外のウェブ プロパティに配置可能です。マッチ タグの構成は次のようになっています。

<img src="http://cm.g.doubleclick.net/pixel?google_nid=1234&google_cm" />

1234」の部分は、Google から提供される購入者 ID に置き換えてください。

このタグは、対象ユーザーに一致するエントリがない場合(またはエントリが古い場合)にのみ配信してください。

ユーザーのブラウザからこのタグに対するリクエストがあると、Google は購入者に 302 リダイレクトを発行します。この 302 リダイレクトでは、URL に Google ユーザー ID とバージョン番号が含まれ、リクエスト ヘッダーに購入者の Cookie が含まれます。このリダイレクトのベース URL は購入者が指定するもので、URL パラメータは Google が追加するものです。

たとえば、購入者が次のようなベース URL を指定したとします。

http://ad.network.com/pixel

すると、Google がリダイレクする URL は次のようになります。

http://ad.network.com/pixel?google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1

google_gid パラメータで渡される Google ユーザー ID は、パディングされていない URL セーフの Base64 エンコード文字列です。マッチ テーブルには、Cookie マッチング サービスで返された文字列をそのまま保存することをおすすめします。

: BidRequest プロトコル バッファの google_user_id フィールドは、Cookie マッチング サービスで返される Google ユーザー ID に対応しています。

google_cver パラメータは、Google ユーザー ID のバージョン番号を示します。Cookie の難読化方式はまれに変更されますが、そのたびに google_cver の値が増加します。

このリダイレクト(リクエスト ヘッダーに購入者 Cookie を含む)が届いたら、購入者はマッチ テーブルを更新し、この購入者 Cookie と Google ユーザー ID を関連付けます。そして、ユーザーのブラウザに 1×1 の見えない画像ピクセルを配信するか、中身のない 204 レスポンスを返す必要があります。

マッチ テーブルのエントリは、マッチ タグがユニーク ユーザーに配信されるたびに追加されます。

このプロセスの詳細について、次の図をご覧ください。個々のリクエストやレスポンスは矢印で示され、リクエストやレスポンスに付随するデータ アイテムは括弧内に記載されています。

リクエストには追加の URL パラメータを設定することも可能で、その場合は次のようなリダイレクトでサーバーに渡されます。

<img src="http://cm.g.doubleclick.net/pixel?google_nid=1234&google_cm&extra1=xx&extra2=yy" />

先頭に google_ が付かないパラメータは、すべてリダイレクト URL にコピーされます。パラメータが Cookie マッチング サービスに渡される順序は重要ではないため、追加パラメータがリダイレクト URL の順序で渡される保証もありません。

http://ad.network.com/pixel?google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1&extra1=xx&extra2=yy

これらのパラメータを使用すると、インプレッションについての追加情報を受け渡すことができます。追加パラメータは、1 キロバイトを超えないようにしてください。

Cookie マッチング サービスへのリクエストには、http の代わりに https を使用することもできます。その場合、リダイレクト URL のプロトコルは http ではなく https になります。

Cookie マッチングの目に見える流れと、背後に横たわる仕組みをご理解いただくため、2 つの例をご覧ください。

例 1: Cookie のクリア

山田さんがすべての Cookie のキャッシュをクリアした後に、ExampleNews.com のホームページにアクセスします。

その際の処理の流れは次のとおりです。

  1. ExampleNews.com が表示され、Google(DoubleClick for Publishers)に対して広告の呼び出しが行われます。
  2. ダイナミック アロケーションに対応している広告ユニットであったため、Ad Exchange から最適な DSP である FinestDSP に入札リクエストが送信されます。
  3. FinestDSP の入札エンジンで入札リクエストが処理され、Ad Exchange に入札レスポンスが送信されます。
  4. FinestDSP がオークションに勝ち、広告とマッチ タグ(ピクセル)が Ad Exchange に送信されます。
  5. Ad Exchange により FinestDSP の広告とマッチ タグが山田さんに配信され、山田さんの DoubleClick Cookie も設定されます。
  6. マッチ タグから Google の Cookie マッチング サービスが呼び出されます。
  7. Cookie マッチング サービスにより山田さんの DoubleClick Cookie が読み取られ、google_user_id を設定したリダイレクトが FinestDSP に送信されます。
  8. ブラウザで FinestDSP の URL が読み込まれます。
  9. FinestDSP で Cookie が生成され、山田さんの google_user_id と関連付けてマッチ テーブルに保存されます。
  10. FinestDSP から山田さんのブラウザに Cookie が送信され、リダイレクトへのレスポンスとして 1×1 の見えないピクセルが送信されます。

例 2: 購入者と DoubleClick の Cookie

例 1 の 1 週間後に、山田さんが ExampleNews.com に再びアクセスしました。山田さんのコンピュータには、既に購入者の Cookie と DoubleClick Cookie が存在します。では、それを踏まえてマッチングの流れを見てみましょう。

  1. ウェブページが表示され、HTML コードにより Google 広告の呼び出しが行われます。
  2. 広告オークションで DoubleClick Ad Exchange から入札リクエストが送信された RTB 購入者(最適な DSP である FinestDSP)は、そのインプレッションに入札可能となります。
  3. FinestDSP には、入札リクエストと一緒にインプレッション情報と google_user_id が届きます。
  4. FinestDSP ではマッチ テーブルで google_user_id を調べ、例 1 で 1 週間前に作成された Cookie を見つけます。
  5. FinestDSP では、その Cookie に関連付けられた情報に基づいて、適切な条件でインプレッションに入札して落札します。
  6. FinestDSP で所有する情報に基づいて、山田さんの関心に合わせてカスタマイズされた広告が表示されます。

トップへ戻る

Cookie マッチング サービスの使用方法

このセクションでは、購入者による Cookie マッチング サービスの使用方法を説明します。

前提条件

Cookie マッチング サービスを使用するには、次の条件を満たしている必要があります。

  • Ad Exchange アカウントがある
  • リアルタイム ビッダーが動作している

次に、Google にリダイレクト URL を通知する必要があります。この URL は、マッチ タグからのリクエストを Cookie マッチング サービスでリダイレクトする先の URL になります。このリクエストは、Cookie マッチングの仕組みで説明したとおり、ユーザーのブラウザから発信されます。

リダイレクト URL は、Ad Exchange のアカウント担当者を通じて Google に通知できます。また、Ad Exchange Buyer REST API をご利用の場合は、アカウントのリソースを更新するメソッドを使用してリダイレクト URL を設定することもできます。

Cookie マッチ タグの配信

Google 提供のマッチ タグ(ピクセル)をユーザーのブラウザに配置できる必要があります。このピクセルは、配信される広告と一緒に配置するか、管理下にあるウェブ プロパティに配置します。

ピクセルの配信

ご利用のサーバーでは、リダイレクト URL を識別し、適切なタイミングでユーザーのブラウザに 1×1 の空のピクセルを配信する必要があります。また、リダイレクト URL へのリクエストを処理しながら、その URL を解析して Google ユーザー ID とエラー コードを抽出し、マッチ テーブルを更新することも必要です。

エラーの処理

Cookie マッチング サービスでは、リダイレクトの特殊な URL パラメータ google_error でエラーが通知されます。このパラメータの値は数値で、発生した個々のエラーに対応する値が示されます。URL パラメータ google_error がある場合も、必ず 1×1 の空ピクセルを送信して応答します。

エラーがあった場合は、関連する購入者 Cookie のマッチ タグを再表示できます。

トップへ戻る

ピクセル マッチング

Cookie マッチング サービスでは、インプレッションを落札した購入者が Google ユーザー ID と Cookie を関連付けることができます。一方、Google の Cookie マッチング コードのもう 1 つの構成要素であるピクセル マッチングでは、その Google ユーザー ID と一致する Cookie を持つもう 1 人の購入者が自動的に(アルゴリズムに基づいて)選定され、そのインプレッションで設定されるマッチ タグに、この選ばれた購入者の URL も含まれます。

これにより、次の処理が可能になります。

  1. ユーザーのブラウザでページが読み込まれた際に、選ばれた購入者に対してマッチ タグでピクセル リクエストが生成されます。
    • ピクセル マッチングの購入者に選定された場合:
      1. ご自身の Cookie と Google ユーザー ID が届きます。これにより、マッチ テーブルでこの 2 つのデータを関連付けることができます。
      2. 必ず Google にリクエストをリダイレクトします。
  2. 選定された購入者がリダイレクトで応答します。
  3. Google にリダイレクトが届くと、そのユーザーと購入者のマッチ データが保存されます。
  4. Google により、ピクセルがブラウザに配信されます。

ピクセル マッチングは、この付加的なマッチングが無効にされているプロパティでは行われません。

ピクセル マッチングの仕組み

Google がページに配置するマッチ タグは、購入者から提供された URL に Google ユーザー ID(google_gid パラメータ)と新しい google_push パラメータを組み合わせたもので、次のような構成になります。

  • <img src=”http://ad.network.com/pixel?google_gid=abcdef&google_cver=1&google_push=abcd” />

このマッチ タグから購入者にピクセルのリクエストが届きます(下図のアイテム 1 を参照)。リクエストを受信した購入者は、次のような構成の URL にリダイレクトする必要があります。

  • http://cm.g.doubleclick.net/pixel?google_nid=1234&google_push=abcd

この URL は、購入者が設定する Cookie マッチングで使われる URL に似ていますが、google_cm パラメータが google_push パラメータに置き換えられています。購入者は google_ulagoogle_hm などのパラメータを追加することもできます。

: 同じリクエストに google_push パラメータと google_cm パラメータを両方設定することはできません。

下の図では、購入者からブラウザに送信されるレスポンスがアイテム 2 で、ブラウザから Google に送信されるリダイレクトがアイテム 3 で示されています。

リダイレクトが届くと、Google では見えないピクセルを返し(図のアイテム 4)、そのユーザーに対してマッチ データが作成されたことを記録します。また、ホスト型マッチ テーブルへのデータの保存や、ユーザー リストへのユーザーの追加など、他にリクエストされた処理がある場合は、それも行います。ユーザーと購入者とのマッチ データの有効期限は 14 日間で、この期間が過ぎると再度マッチングが行われます。

下の図では、個々のリクエストやレスポンスが矢印で示され、リクエストやレスポンスに付随するデータ アイテムが括弧内に記載されています。

トップへ戻る

制限事項

このセクションでは、ユーザーのプライバシーを保護し、快適な利便性を確保するために、Google が設定している制限について説明します。

ユーザーのプライバシーの確保

Cookie マッチング サービスでは、次の原則に従ってユーザーのプライバシーを保護しています。

  • 購入者からのユーザー情報(購入者の Cookie やユーザー属性など)を受け取らない。
  • 複数の購入者がマッチ テーブルを 1 つにまとめることを認めない。
  • Cookie マッチング サービスで Google の DoubleClick Cookie を公開しない。
  • マッチ テーブルの目的は、Google と接点のあるユーザーに関して、購入者が独自の情報を利用できるようにすることで、Ad Exchange の規約やポリシーに記載されているとおり、いかなる場合でも、データ収集を目的として Cookie マッチング サービスを使用することは認めない。

ビッダーでは上記の原則を遵守し、稼働時にはユーザーのプライバシーを保護するようにしてください。

フリークエンシー キャップ

購入者は Cookie マッチング サービスにフリークエンシー キャップを設定し、マッチ テーブルに有効なエントリがあるユーザーに対しては、このサービスを使用しないように管理する必要があります。Cookie マッチングのタグは、該当するユーザーのエントリがマッチ テーブルにないか、エントリが古い場合のみ配信するようにしてください。設定から 15 日以上経過したエントリは、期限切れと見なして更新できます。

Google では配信時のフリークエンシー キャップの設定を強制してはいませんが、フリークエンシー キャップに関するポリシーが守られているかどうかを定期的に確認し、違反していることが判明した場合は、この無料サービスの利用を停止する権利を有します。

すべてのピクセル マッチング リクエストへのレスポンス

ピクセル マッチング サービスを利用される場合は、すべてのピクセル マッチング リクエストにレスポンスを返す必要があります。これは、このサービスの利用方法を定めた種々のポリシーが遵守されているかどうかを Google で確認できるようにするためです。レスポンス率が 90% を下回ると、アカウントに送信されるピクセル マッチング リクエストの数が抑制されます。

上限リクエスト レートの遵守

Cookie マッチング サービスに登録すると Google から上限リクエスト レートが設定され、この上限レートが守られているかどうかトランザクションが確認されます。

トップへ戻る

API の仕様

マッチ タグ

マッチ タグには、購入者 ID(google_nid パラメータで渡されます)に加え、Cookie マッチング サービスの URL も含める必要があります。この URL のプロトコルは http でも https でもかまいません。マッチ タグの有効な URL の例は次のとおりです。

http://cm.g.doubleclick.net/pixel?google_nid=my_nid
https://cm.g.doubleclick.net/pixel?google_nid=my_nid
: 上記のリクエストでは操作が指定されていないため、いかなる処理も行われません。

Google では API の将来的な拡張に備えて、google_ で始まるマッチング サービスの URL パラメータをすべて予約しています。マッチ タグに追加されたその他の URL パラメータは、リダイレクト URL にそのまま渡されます。

Cookie マッチング サービスでは、次の操作が可能です。

  • Cookie マッチングの実行 -- 前述の基本的な Cookie マッチング操作。
  • ユーザー リストへのユーザーの追加 -- ユーザー リストにユーザーを追加できるため、そのためのタグが不要になります。
  • Cookie の設定(未設定の場合) -- 通常は、Cookie マッチング サービスによってユーザーのブラウザに doubleclick.net の Cookie が設定されることはありませんが、このオプションを設定すると、Cookie マッチング サービスで doubleclick.net の Cookie が設定されます(まだ設定されていない場合)。

これらの操作では、次の URL パラメータを使用できます。

パラメータ 説明
google_nid ネットワーク ID で、これが購入者 ID になります。この「ネットワーク」とは一般的な購入者である広告ネットワークを意味します。Cookie マッチング V1 では nid パラメータが同じ機能を持ちます。
google_cm Cookie のマッチングを実行します。このパラメータの設定値は無視されるので、省略することもできます。
google_sc Cookie が存在しない場合、新たに設定します。このパラメータの値は無視されるので、省略することもできます。このパラメータを省略すると、Doubleclick Cookie が存在しない場合にエラーが発生します。
google_no_sc Cookie が存在しない場合、新たに設定しません。このパラメータの値は無視されるので、省略することもできます。
google_ula ユーザー リストにユーザーを追加します。値は userlistid[,timestamp] の形式を使用します。
  • userlistid: 1 つの数字で構成されるユーザー リスト ID です。
  • timestamp: POSIX 形式のオプションのタイムスタンプで、ユーザー リストにユーザーが追加された時刻を示します。
この URL パラメータを繰り返し設定すると、複数のリストにユーザーを追加できます。

Cookie マッチング サービスでは、google_ で始まる他のパラメータはすべて無視され、リダイレクト URL には渡されません。先頭に google_ が付かないパラメータは、レスポンス用 google_ パラメータと一緒にリダイレクト URL に追加されます(下記の「リダイレクト URL」のセクションをご覧ください)。

パラメータの順序は重要ではありません。有効な URL と無効な URL については、のセクションをご覧ください。

注: google_hm パラメータについては、ホスト型マッチ テーブルのセクションをご覧ください。

トップへ戻る

リダイレクト URL

google_ で始まるすべての URL パラメータは、将来的な API の拡張に備えて予約されています。

リダイレクト URL は次の要素で構成されます。

  • マッチ タグの呼び出しに使われたプロトコル(http または https)。
  • Google に通知されたリダイレクト用のベース URL(ハードコードされた URL パラメータの場合もあります)。
  • レスポンス用 google_ パラメータ(マッチ タグで購入者が指定したリクエスト用 google_ パラメータに応じて変わります)。
  • マッチ タグで送信された追加の URL パラメータ(先頭に google_ が付かないもの)。

次の google_ レスポンス パラメータの定義は次のとおりです。

パラメータ 説明
google_error リクエストの全体的なエラー。操作が実行されていないため、他の google_ レスポンス パラメータは設定されません。エラー コードは、次のいずれかの整数値です。
  • 1 - ユーザーの Google Cookie は設定されていますが、その Cookie を使ったトラッキングが無効に設定されています。このパラメータは、Cookie マッチング サービス API V1 の E1 と同じ意味で使用されます。
  • 2 - 有効な操作が指定されていません(操作が指定されていないリクエストを受信した場合など)。
  • 3 - ユーザーの Google Cookie が設定されていません。Cookie マッチング サービスでは Cookie は設定されません。このパラメータは、Cookie マッチング サービス API V1 の E0 と同じ意味で使用されます。
  • 4 - 矛盾する操作が指定されています。同じリクエストで google_push パラメータと google_cm パラメータを同時に指定することはできません(パラメータの目的が矛盾するためです)。
google_gid Google ユーザー ID です。google_cm を指定したリクエストが成功した場合に設定されます。
google_cver Cookie のバージョンです。google_cm を指定したリクエストが成功した場合に設定されます。このパラメータは、Cookie マッチング サービス API V1 の cver と同じ意味で使用されます。
google_ula

ユーザーをリストに追加する操作のステータスです。リクエストで複数の google_ula が指定されていた場合は繰り返されます。形式は次のとおりです。
<userlistid>,<status code>

例: google_ula=1234567890,0

google_ula 操作では、次のいずれかのステータス コードが返されます。

  • 0 - エラーはありません。ユーザーがユーザー リストに追加されました。
  • 2 - 拒否されました。指定されたユーザー リストにユーザーを追加する権限がありません。
  • 5 - 指定されたユーザー リスト ID が無効です。
  • 6 - 指定されたユーザー リスト ID が非公開に設定されています。
  • 10 - Cookie マッチング サービスで内部エラーが発生しました。ユーザーのマッチングを再試行することもできます。

ホスト型マッチ テーブル

マッチ テーブルは、Google でホストするよう設定できます。Google でホストすると、テーブルのサイズやマッチ率に関するレポートの機能を改善し、サポートが必要なインフラストラクチャの数を減らすことができます。

Google のホスト型マッチ テーブルでは、購入者が保存のために Google に渡したデータが、その後の入札リクエストで返される仕組みになっています。通常、購入者が独自の Cookie ID で識別したユーザーに対してマッチ タグを設定した場合は、Google に送信する Cookie マッチ リクエストにその Cookie ID を含めます。Google では送信されたデータをホストし、その後の同じユーザーによるインプレッションに対する入札リクエストに、そのデータを含めます。この仕組みを使用すると、次のことが可能になります。

  • Google ユーザー ID と独自の Cookie との関連付けを保存するステップを省略する
  • マッチ テーブルにエントリがあるユーザーの場合に限って、入札リクエストを受け取るよう設定する

google_hm パラメータは、Cookie マッチ リクエストで Google に渡すデータを格納するコンテナとして機能します。Google から 302 リダイレクトで応答があった場合は、google_hm パラメータでエラー コードが渡されます。

Google がデータを返す必要がある場合は、入札リクエストの hosted_match_data フィールドで返されます。hosted_match_data フィールドの詳細については realtime-bidding-proto ファイルをご覧ください。

google_hm: Cookie マッチ リクエスト パラメータの場合

パラメータ 説明
google_hm 購入者が Google のホスト型マッチ テーブルでの保存を希望するデータが含まれます。値は URL セーフの Base64 文字列(パディングは任意)です。

google_hm: リダイレクト パラメータの場合

パラメータ 説明
google_hm ホスト型マッチ テーブルへのデータの書き込みが失敗した場合に限って使用されます。その場合、このパラメータの値は次のいずれかのステータス コードになります。
  • 1 - 禁止: ホスト型マッチ テーブルにエントリを書き込む権限がありません。
  • 2 - デコード エラー: パラメータの値をデコードできませんでした。
  • 3 - ペイロードが長すぎる: パラメータの値が 24 バイト以上のデータにデコードされました。
  • 4 - 内部エラー: データの保存中に内部エラーが発生しました。
  • 5 - 抑制: 書き込みが抑制されているため、この書き込みは処理されませんでした。

下のをご覧ください。

トップへ戻る

Cookie マッチング サービス API V1 からの移行

重要: ここでは Cookie マッチング サービス API の最新バージョンである V2 について説明します。API の V1 から V2 へスムーズに移行するには、説明どおりの順序でステップを行い、1 つのステップを完了してから次のステップに移ってください。

ステップ 1: 新しい URL パラメータに対応する

サーバーの設定を修正して、V2 のリダイレクト URL の google_ パラメータを受け取れるようにします。サーバーでは少なくとも次のパラメータに対応する必要があります。

  • google_error
  • google_gid
  • google_cver

V1 から V2 へスムーズに移行するには、これらのリダイレクト URL のパラメータを処理できる状態にしておくことが重要です。

マッチ タグを使用してユーザー リストにユーザーを追加する場合は、google_ula パラメータにも対応できるようにサーバーを修正する必要があります。

ステップ 2: マッチ タグを修正する

サーバーの修正が完了したら、リクエスト URL の新しいパラメータを使用できるよう、次のようにマッチ タグを修正します。

  • リクエスト URL の nid パラメータを google_nid に変更します。
  • Cookie マッチングを起動するための google_cm パラメータを追加します。
  • Doubleclick Cookie が存在しない場合に、新しい Cookie を設定しないようにするには、リクエスト URL の google_no_sc パラメータを設定します。ただし、Doubleclick Cookie が存在しない場合に google_no_sc パラメータが設定されていると、マッチングは行われません。
  • マッチ タグを使用してユーザー リストにユーザーを追加する場合は、リクエスト URL の google_ula パラメータを設定します。

たとえば、マッチ タグのソースとして V1 で次のような URL を使用していたとします。

http://cm.g.doubleclick.net/pixel?nid=ad_network_xyz

この場合、V2 では次のような URL を使用します(必要に応じて &google_sc も追加できます)。

http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm
注: リクエスト URL に google_nid パラメータがあると、API V2 が起動されます。このため、リダイレクト URL の新しいパラメータを処理できるようにサーバーを修正し、さらにリクエスト URL に google_cm を追加する場合に限り、nid の代わりに google_nid を設定してください。

ステップ 3: 設定済みのリダイレクト URL を修正する(オプション)

これまで、リダイレクト URL が次のように設定されていたとします。

http://ad.network.com/pixel?id=

この場合、URL パラメータ id は不要になる(Cookie は必ず google_gid を使用して設定されるようになる)ため、この設定済みの URL は次のように修正できます。

http://ad.network.com/pixel

これで、不要な URL パラメータ id はサーバーに送信されなくなります。今後はこのパラメータを使用しないようにしてください。

設定済みのリダイレクト URL を修正する場合は、担当のテクニカル アカウント マネージャーまでご連絡ください。

トップへ戻る

Cookie マッチング マクロ

V2 では、必要に応じて「%%GOOGLE_GID%%」か「%%GOOGLE_GID_PAIR%%」の形式のマクロを使用して URL を設定できるようになりました。「%%GOOGLE_GID%%」は google_gid の値に直接代入され、「%%GOOGLE_GID_PAIR%%」は google_gid=value に代入されます。

サポートされるマクロは次のとおりです。

マクロ 展開先
GOOGLE_GID <Google ユーザー ID>
GOOGLE_GID_PAIR &google_gid=<Google ユーザー ID>
GOOGLE_CVER <Cookie のバージョン番号>
GOOGLE_CVER_PAIR &cver=<Cookie のバージョン番号>
GOOGLE_ERROR <エラー ID>
GOOGLE_ERROR_PAIR &google_error=<エラー ID>
GOOGLE_PUSH <ピクセル マッチング データ>
GOOGLE_PUSH_PAIR &google_push=<ピクセル マッチング データ>
GOOGLE_ALL_PARAMS google_gid=<Google ユーザー ID>&cver=<Cookie のバージョン番号>&google_error=<エラー ID>

トップへ戻る

基本的なリクエスト

最も基本的な Cookie マッチ リクエストには追加パラメータがありません。その場合、マッチ タグの URL は次のようになります。

  • V1 の場合: http://cm.g.doubleclick.net/pixel?nid=ad_network_xyz
  • V2 の場合: http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm

設定済みのリダイレクト URL が次のようだったと仮定します。

  • http://ad.network.com/pixel?id=

この場合、レスポンスの成功例は次のようになります。

  • V1 の場合: http://ad.network.com/pixel?id=dGhpcyBpcyBhbiBleGFtGxl&cver=1
  • V2 の場合: http://ad.network.com/pixel?id=&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1

ユーザーの doubleclick.net Cookie が設定されていない場合、レスポンスは次のようになります。

  • V1 の場合: http://ad.network.com/pixel?id=E0
  • V2 の場合: http://ad.network.com/pixel?id=&google_error=3

ユーザーの doubleclick.net Cookie が設定されていても、行動ターゲティングが無効に設定されている場合は、上の例のエラー コードがそれぞれ E11 になります。

トップへ戻る

マッチ タグの追加パラメータ

先頭に google_ が付かないパラメータをマッチ タグに追加すると、それらはサーバーに渡されます。ここでは、p1=v1p2=v2 の 2 つの追加パラメータを例として使用します。

この場合、マッチ タグの URL は次のようになります。

  • V1 の場合: http://cm.g.doubleclick.net/pixel?nid=ad_network_xyz&p1=v1&p2=v2
  • V2 の場合: http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm&p1=v1&p2=v2

そして、レスポンスの成功例は次のようになります。

  • V1 の場合: http://ad.network.com/pixel?id=dGhpcyBpcyBhbiBleGFtGxl&cver=1&p1=v1&p2=v2
  • V2 の場合: http://ad.network.com/pixel?id=&p1=v1&p2=v2&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1
: V2 では V1 のように追加パラメータが URL の末尾に付くとは限りません。パラメータの順序は重要ではないため、これは問題になりません。

エラー レスポンスでも同じように追加パラメータが付加されますが、エラーの報告については基本的なリクエストの例をご覧ください。

トップへ戻る

設定済みリダイレクト URL の追加パラメータ

設定済みの URL が次のようだったと仮定します。

  • http://ad.network.com/pixel?id=&p1=v1&p2=v2

さらに、次のような基本的なマッチ タグ URL を使用しているとします。

  • V1 の場合: http://cm.g.doubleclick.net/pixel?nid=ad_network_xyz
  • V2 の場合: http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm

この場合、レスポンスの成功例は次のようになります。

  • V1 の場合: http://ad.network.com/pixel?id=dGhpcyBpcyBhbiBleGFtGxl&cver=1&p1=v1&p2=v2
  • V2 の場合: http://ad.network.com/pixel?id=&p1=v1&p2=v2&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1

エラー レスポンスでも同じように追加パラメータが付加されますが、エラーの報告については基本的なリクエストの例をご覧ください。

トップへ戻る

google_ パラメータの使用方法

マッチ タグの URL や設定済みのリダイレクト URL を使って google_ で始まる追加パラメータを渡そうとしても、V2 のリダイレクトではパラメータがサーバーに渡されません。

たとえば、設定済みの基本的なリダイレクト URL を使って、次の 2 つのマッチ タグ URL を設定したとします。

  • V1 の場合: http://cm.g.doubleclick.net/pixel?nid=ad_network_xyz&google_p1=v1&p2=v2
  • V2 の場合: http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm&google_p1=v1&p2=v2

この場合、レスポンスの成功例は次のようになります。

  • V1 の場合: http://ad.network.com/pixel?id=dGhpcyBpcyBhbiBleGFtGxl&cver=1&google_p1=v1&p2=v2
  • V2 の場合: http://ad.network.com/pixel?id=&p2=v2&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1

ご覧のとおり、V1 の API では google_p1 パラメータが渡されていますが、V2 では渡されていません。

エラー レスポンスでも同じようにパラメータが追加されますが(V1 では両方とも、V2 では p2 のみ)、エラーの報告は基本的な例のように行われます。

トップへ戻る

google_ula パラメータの使用方法

設定済みのリダイレクト URL が次のようだったと仮定します。

  • http://ad.network.com/pixel?id=

さらに、次のようなマッチ タグ URL を使用しているとします。

  • http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345

これが成功すると、ユーザーは次の URL にリダイレクトされます。

  • http://ad.network.com/pixel?id=&google_ula=12345,0

全体的なエラーが発生した場合(ユーザーの doubleclick.net Cookie が設定されていないなど)、リダイレクト URL は次のようになります。

  • http://ad.network.com/pixel?id=&google_error=3

次のようにタイムスタンプを指定することもできます。

  • http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345,7654321

この場合、成功時のリダイレクト URL は先ほどと同じになります。

エラーが生じた場合のリダイレクト URL も同様ですが、ステータス コードは異なります。ユーザー リスト 12345 にユーザーを追加する権限がなかった場合、リダイレクト URL は次のようになります。

  • http://ad.network.com/pixel?id=&google_ula=12345,2

次のように、複数の google_ula パラメータを使って、複数のリストを指定することもできます。その場合、タイムスタンプは個別に指定できます。

  • http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345,7654321&google_ula=45678

各操作のステータスは、次のようなリダイレクト URL で個別に報告されます。

  • http://ad.network.com/pixel?id=&google_ula=12345,2&google_ula=45678,0

これを見ると、ユーザーはリスト 45678 に追加されましたが、リスト 12345 で権限エラーが発生しています。

次のように、リクエスト パラメータの google_ulagoogle_cm を組み合わせると、一度のリクエストで Cookie マッチングの起動とユーザー リストへのユーザーの追加を実施できます。

  • http://ad.network.com/pixel?id=&google_ula=12345&google_cm

この場合、リダイレクト URL は次のようになります。

  • http://ad.network.com/pixel?id=&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1&google_ula=12345,0

トップへ戻る

google_sc パラメータと google_no_sc パラメータの使用方法

google_no_sc
リクエスト パラメータ google_no_sc を使用すると、ユーザーの doubleclick.net Cookie が設定されていない場合でも、Cookie マッチング サービスで設定しないように指定できます(デフォルトでは、こうした場合に Cookie が設定されます)。
google_sc

リクエスト パラメータ google_sc を使用すると、ユーザーの doubleclick.net Cookie が設定されていない場合に、Cookie マッチング サービスで Cookie が設定されます。

これらのパラメータでは、この他のリクエストの結果が変わることはありません。なお、Cookie マッチング サービスで、必ずしも Cookie を設定できるとは限りません。たとえば、ユーザーが Cookie 全般を許可していない場合や、doubleclick.net Cookie を許可していない場合などは、Cookie を設定できません。

Cookie を設定する必要がある場合、Cookie マッチング サービスではユーザーのブラウザで Cookie の設定が可能かどうかを確認するため、Set-Cookie ヘッダーを使って自己リダイレクトを発行します。自己リダイレクトで Cookie が送られてこないブラウザは、doubleclick.net Cookie を受け付けないブラウザに分類され、自己リダイレクトに google_error=3 が含まれます。

設定済みのリダイレクト URL が次のようだったと仮定します。

  • http://ad.network.com/pixel?id=

さらに、次のようなマッチ タグ URL を使用しているとします。

  • http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345

このとき、ユーザーの doubleclick.net Cookie が設定されておらず、リクエスト パラメータ google_no_sc を使用した場合、リダイレクト URL は次のようになります。

  • http://ad.network.com/pixel?id=&google_error=3

一方、リクエスト パラメータ google_cm を指定して Cookie が正常に設定された場合、リダイレクト URL は次のようになります。

  • http://ad.network.com/pixel?id=&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1
: ユーザーの doubleclick.net Cookie が新しく設定されたものか、既存のものかを確認する方法はありません。

Cookie を設定できなかった場合、リダイレクト URL はエラー発生時の通常のリダイレクト URL と同じで、次のようになります。

  • http://ad.network.com/pixel?id=&google_error=3

トップへ戻る

ホスト型マッチ テーブル: 書き込み成功

この例では、次の値が使用されたと仮定します。

  • google_hm パラメータ: "Cookie number 1!" (URL セーフの Base64 で「Q29va2llIG51bWJlciAxIQ==」としてエンコード)
  • 設定済みのリダイレクト URL: http://cookie-monster.com/pixel?id=

そして、Cookie マッチ リクエストが次のようだったとします。

http://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=Q29va2llIG51bWJlciAxIQ%3D%3D

さらに、302 リダイレクトが次のようだったとします。

  • http://cookie-monster.com/pixel?id=

この例では google_hm パラメータに "Cookie number 1!" のエンコード値を設定したため、この後の同じユーザーへのインプレッションに対する入札リクエストでは、次のように hosted_match_data フィールドにその値が含まれます。

BidRequest <
  ...
  hosted_match_data: "Cookie number 1!"
>

この例では、次のような結果になります。

  • リクエストで google_cm を設定しなかったため、レスポンスに google_gid は含まれません。
  • ホスト型マッチ テーブルへの書き込みが成功したため、レスポンスに google_hm は含まれません。
  • 書き込みが成功したため、この後の入札リクエストではホストされたデータを使用できるようになります。

トップへ戻る

ホスト型マッチ テーブル: デコード エラー

この例では、設定済みのリダイレクト URL が次のようだったと仮定します。

  • http://cookie-monster.com/pixel?id=

そして、Cookie マッチ リクエストが次のようだったとします。

http://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=chocolate_chunk!

ここで、購入者は google_hm パラメータを追加していますが、その値をエンコードせずに chocolate_chunk! の値をそのまま設定しようとしている点にご注目ください。

さらに、302 リダイレクトが次のようだったとします。

  • http://cookie-monster.com/pixel?id=&google_hm=2

この例では、次のような結果になります。

  • リクエストで google_cm を設定しなかったため、レスポンスに google_gid は含まれません。
  • Cookie マッチング サービスでは、google_hm パラメータの値を URL セーフの Base64 としてデコードしようとします。しかし、chocolate_chunk! は Base64 として正常にデコードできないため、ホスト型マッチ テーブルへの書き込みは失敗します。
  • ホスト型マッチ テーブルへの書き込みに失敗したため、レスポンスで google_hm が使用され、デコード エラーを示すエラー コード 2 が含まれます。
  • この書き込みは失敗したため、その後の入札リクエストで新しいマッチ データを使用することはできません(ただし、古いデータは送られます)。

トップへ戻る

ホスト型マッチ テーブル: Cookie なしエラー

さまざまな理由から、すべてのユーザーが常に doubleclick.net Cookie を設定しているとは限りません。

この例では、ユーザーのブラウザに doubleclick.net Cookie が設定されていないと仮定します。また、設定済みのリダイレクト URL が次のようだったと仮定します。

  • http://cookie-monster.com/pixel?id=

そして、Cookie マッチ リクエストが次のようだったとします。

http://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=chocolate_chunk!

ここで、購入者は google_hm パラメータを追加していますが、その値をエンコードせずに chocolate_chunk! の値をそのまま設定しようとしている点にご注目ください。

さらに、302 リダイレクトが次のようだったとします。

  • http://cookie-monster.com/pixel?id=&google_error=3

この例では、次のような結果になります。

  • Cookie が設定されていない場合は、リクエスト全体が失敗するため、レスポンスに google_error が設定されます。
  • この購入者は google_hm にエンコードしていない値を設定したため、Cookie マッチング サービスでこの値をデコードしようとすると失敗します。ただし、このリクエストは全体が失敗し、その高レベルなエラーが優先されるため、google_hm のデコードは行われません。したがって、レスポンスの google_hm にデコード エラーは設定されません。
  • この書き込みは失敗したため、その後の入札リクエストで新しいマッチ データを使用することはできません(ただし、古いデータは送られます)。

トップへ戻る

ホスト型マッチ テーブル: 総合的な例

この例では、次の値が使用されたと仮定します。

  • google_hm パラメータ: "Cookie number 1!"(Base64 で「Q29va2llIG51bWJlciAxIQ==」としてエンコード)
  • google_ula パラメータ: 値 12345
  • 設定済みのリダイレクト URL: http://cookie-monster.com/pixel?id=
  • 追加パラメータ my_extra_param: 値なし
  • 追加パラメータ my_other_extra_param: 値 7

そして、Cookie マッチ リクエストが次のようだったとします。

http://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_cm&google_hm=Q29va2llIG51bWJlciAxIQ%3D%3D&google_ula=12345&my_extra_param=&my_other_extra_param=7

さらに、302 リダイレクトが次のようだったとします。

  • http://cookie-monster.com/pixel?id=&my_extra_parameter=&my_other_extra_param=7&google_gid=ABCDETC&google_cver=1&google_ula=12345,0

この例では、次のような結果になります。

  • 最初に、追加パラメータがそのまま渡されます。
  • google_ula パラメータに、ユーザー リストへの追加操作のステータスが含まれます(0: OK)。
  • ホスト型マッチ テーブルへの書き込みが成功したため、その後の入札リクエストで新たなマッチ データを使用できるようになります。
  • この例では google_hm パラメータに "Cookie number 1!" のエンコード値を設定したため、この後の同じユーザーへのインプレッションに対する入札リクエストでは、次のように hosted_match_data フィールドにその値が含まれます。
BidRequest <
  ...
  hosted_match_data: "Cookie number 1!"
>

トップへ戻る

Cookie マッチング マクロの使用方法

マクロを使用しない場合

通常は、購入者が Cookie マッチングのベース URL を提供し、それに対して Google が Cookie マッチングのパラメータを付加します。

たとえば、購入者が RTB キーを保存した次のような URL を提供したとします。

http://user.buyer.com/cookies?x=0&y=1

すると、Google がこの URL を呼び出す際には、次のようなパラメータが追加されます。

http://user.buyer/cookies?x=0&y=1&google_push=456&google_gid=1&google_cver=1

マクロを使用する場合

パラメータを特定の順序にする必要がある場合は、RTB キーとして次のような URL を提供できます。

http://user.buyer.com/cookies?w=0%%GOOGLE_PUSH_PAIR%%&x=1%%GOOGLE_GID_PAIR&y=2%%GOOGLE_CVER_PAIR%%&z=3%%GOOGLE_ERROR_PAIR%%

このマクロは Google で展開され、次のように残りのパラメータが付加されます。

http://user.buyer.com/cookies?w=0&google_push=456&x=1&google_gid=1&y=2&google_cver=1&z=3

この例では「_PAIR」という形式のマクロが使用されているため、展開されたマクロにはパラメータの名前も含まれます。次の URL でも同じ結果になります。

http://user.buyer.com/cookies?w=0&google_push=%%GOOGLE_PUSH%%&x=1&google_gid=%%GOOGLE_GID%%&y=2&google_cver=%%GOOGLE_CVER%%&z=3%%GOOGLE_ERROR_PAIR%%

トップへ戻る

フィードバックを送信...

DoubleClick Ad Exchange Real-Time Bidding Protocol