このドキュメントでは、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
ここで
- 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 が返されない場合は、リクエストを再試行しないでください。リクエストを停止して、すべてのエラーを修正してください。
ペイロード データ
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 ID と Hit 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 エンコードを行う必要があります。値 /my page € を含む鍵 dp を送信するには、まず 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）
Integer
整数を表すために使用されます。値は符号付きの int64 型として保存されます。
Number
整数または浮動小数点数を表すために使用されます。