Measurement Protocol のリファレンス

このドキュメントでは、Measurement Protocol を使って Google アナリティクスにデータを送る方法を説明します。

概要

Measurement Protocol を使って Google アナリティクスにデータを送るには、次の 2 つの要素を送ります。

  • トランスポート - データの送り先と送信方法
  • ペイロード - 送信するデータ

このドキュメントでは、両方の要素を記述する形式について説明します。

トランスポート

URL エンドポイント

Measurement Protocol を使って、次のエンドポイントに HTTP リクエストを行ってデータを 送ります。

https://www.google-analytics.com/collect

HTTPS プロトコルを使用してすべてのデータを安全に送る必要があります。

データは POST リクエストか GET リクエストを使って送信 できます。

POST を使用する場合

データを送る際には、比較的大きなペイロードを送信可能な POST を使うことをおすすめします。POST を使う場合は、次の HTTP リクエストを発行します。

User-Agent: user_agent_string
POST https://www.google-analytics.com/collect
payload_data

上記の HTTP リクエストの内容は次のとおりです。

  • user_agent_string - 形式に沿ったユーザー エージェント文字列で、ブラウザ、プラットフォーム、モバイル機能のディメンションを算出するために使われます。

    この値が設定されていない場合、上記のデータは算出されません。

  • payload_data - POST リクエストの BODY(本文)です。本文には URI エンコードしたペイロード 1 つだけを含め、8,192 バイト以下にする必要があります。
  • IP アドレス - この HTTP リクエストで暗黙的に送られ、Google アナリティクスで地域とネットワークに関するすべてのディメンションを算出する際に使用されます。

GET を使用する場合

POST データを送信できない環境の場合は、次のように同じエンドポイントに対して HTTP GET リクエストを送ることも可能です。

GET /collect?payload_data HTTP/1.1
Host: https://www.google-analytics.com
User-Agent: user_agent_string

この場合、ペイロード データは URI エスケープしたクエリ パラメータとして送られます。 エンコードされた URL 全体の長さは 8,000 バイト以下にする必要があります。

キャッシュの無効化

一部の環境(ブラウザなど)では、HTTP GET リクエストがキャッシュされる場合があります。リクエストがキャッシュされると、後続のリクエストがキャッシュから取得され、Google アナリティクスに送られない可能性があります。このため Measurement Protocol ではキャッシュを無効化するための特殊なパラメータ(z)が用意されており、これにランダムな数字を設定できます。このパラメータにランダムな値を設定すれば、Measurement Protocol のすべてのリクエストが固有のものとなり、後続のリクエストがキャッシュから取得されることがなくなります。

キャッシュの無効化を行う場合は、このパラメータをペイロードの最後のパラメータとして追加してください。

https://www.google-analytics.com/collect?payload_data&z=123456

レスポンス コード

Measurement Protocol は HTTP リクエストを受け取ると 2xx ステータス コードを返します。ペイロード データの形式が不適切であったり、ペイロードのデータが間違っていたり Google アナリティクスで処理されていなかったりしても、Measurement Protocol からエラーコードが返されることはありません。

2xx ステータス コードが返されない場合は、その HTTP リクエストの再発行をせずに、リクエストを停止してエラーを修正してください。

ペイロード データ

Measurement Protocol を使って Google アナリティクスで収集されるデータはすべて、ペイロードとして送られます。ペイロードは、それぞれのパラメータがキーと値を持つ URL クエリ文字列に似たもので、各ペイロードが「=」で区切られ、キーと値のペアが「&」で区切られます。具体的には、次のような形式になります。

key1=val1&key2=val2

個々のペイロードには、項目(必須の値、URI エンコード、同時送信可能なパラメータ、パラメータの長さ)を管理するルールがあります。また、各パラメータはそれぞれ独自の形式を必要とする固有のタイプをもちます。次のセクションでは、これらのルールについて説明します。

Measurement Protocol を使って送信できるパラメータの全リストについては、パラメータのリファレンスをご覧ください。

すべてのヒットに必要な値

次のパラメータは個々のペイロードに必要です。

名前 パラメータ 説明
プロトコルのバージョン v v=1 プロトコルのバージョンです。この値は 1 にする必要があります。
トラッキング ID tid tid=UA-123456-1 データの送り先の Google アナリティクス プロパティを識別するための ID です。
クライアント ID cid cid=xxxxx 個々のユーザーに固有の ID です。
ヒットタイプ t t=pageview 個々のユーザーについて収集された操作の種類です。

Client IDHit Type データは、Google アナリティクスのデータモデルにそのまま適用されます。たとえば、/pageA/pageB/pageC にアクセスしたユーザー 5555 をトラッキングする場合は、次の 3 つのペイロードを送ります。

v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageA
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageB
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageC

なお、「/」は「%2F」にエンコードされています。

URL エンコードの値

Google アナリティクスに送る値はすべて、UTF-8 エンコードと URL エンコードを行う必要があります。たとえば、キー「dp」と値「/my page €」を送る場合、値は UTF-8 エンコードしてから URL エンコードする必要があり、結果として次のような文字列になります。

dp=%2Fmy%20page%20%E2%82%AC

不適切にエンコードされた文字があった場合、そうした文字は Unicode の代替文字「xFFFD」に置き換えられます。

特定のヒットタイプに必須の値

一部のパラメータは、特定のヒットタイプの場合にのみ送信されます。たとえばページビュー(pageview)ヒットタイプでは、ページ階層パラメータ(dp)の設定も必要です。ヒットタイプごとに必要となるパラメータについては、パラメータのリファレンスをご覧ください。

最大文字数

Measurement Protocol の一部のテキスト値には、それぞれ最大文字数(バイト単位)があります。たとえば、ドキュメント参照フィールド dr の最大長は 2,048 バイトです。最大文字数を超える値は、超過分の文字が自動的に削除されます。マルチバイトの 1 文字分で最大文字数を超えた場合は、その文字全体が削除されます。

サポートされるデータ型

Measurement Protocol のデータ フィールドはそれぞれ特定の型に属し、独自の検証ルールがあります。検証ルールに合わないパラメータ値があった場合、そのパラメータは無視され Google アナリティクスで処理されません。その他のパラメータはすべて通常どおりに処理されます。

Measurement Protocol では、次のデータ型をサポートしています。

個々のデータ フィールドには独自の制限がある場合があります。すべてのデータ フィールドと対応するデータ型の一覧については、フィールドに関するリファレンスをご覧ください。

テキスト

文字列を表す際に使用されます。テキスト フィールドでは追加処理として、テキストの最初と最後にある空白文字が削除されます。また、テキスト内で 2 個以上の空白文字(スペース、タブ、改行など)が連続している場合は、1 個を残して余分な空白文字が削除されます。こうした変換処理は、上限を超える文字が削除される前の生データに対して行われます。たとえば、次のようなテキストがあったとします。

   Hello      World

この場合、テキストは次のように変換されます。

Hello World

通貨

通貨の総価値を表すために使用します。通貨の整数部と小数部の区切りとして小数点が使用され、小数第 6 位までが有効となります。通貨フィールドでは、次のような値が有効です。

1000.000001

値が Google アナリティクスに送信されると、最初の数字、「-」、または「.(小数点)」までのすべてのテキストが削除されます。たとえば、次のようなテキストがあったとします。

$-55.00

この場合、テキストは次のように変換されます。

-55.00

ブール値

値が真か偽かを判断するために使用されます。有効な値は次のとおりです。

  • 1 - 真(True)
  • 0 - 偽(False)

整数

整数を表すために使用されます。値は符号付きの int64 型として保存されます。

数値

整数または浮動小数点数を表すために使用されます。