Measurement Protocol のリファレンス

このページでは、Measurement Protocol のトランスポート メカニズムとデータ パラメータについて説明します。

トランスポート

すべてのデータは、HTTPS POST リクエストを使用して安全に送信する必要があります。

リクエストを次のエンドポイントに送信します。

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

データを EU で収集する場合は、代わりに次のエンドポイントを使用します。

https://region1.google-analytics.com/mp/collect

POST リクエストの例を次に示します。

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
PAYLOAD_DATA

PAYLOAD_DATA はリクエストのペイロードに置き換えます。

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

ペイロード

ペイロードは 2 つの部分で構成されています。

  1. クエリ パラメータ。
  2. JSON POST 本文。

クエリ パラメータ

パラメータ名 説明

api_secret

 必須。Google アナリティクス管理画面の API Secret。

確認するには、[管理] > [データ ストリーム] > [ストリームを選択] > [Measurement Protocol] > [作成] の順にクリックします。

組織内で限定公開。大量に発生するスパムを回避するために定期的に更新する必要があります。

JSON POST 本文

キー 型 説明

user_id

 string

（省略可）ユーザーの一意の識別子。この識別子について詳しくは、User-ID によるクロスプラットフォーム分析をご覧ください。 使用できるのは UTF-8 の文字のみです。

timestamp_micros

 number

（省略可）Unix タイムスタンプ（マイクロ秒単位）。ミリ秒単位ではありません。イベントの時刻を表します。過去に発生したイベントを記録する場合にのみ設定します。user_property またはイベントのタイムスタンプでオーバーライドできます。イベントには、最大 72 時間前までさかのぼってタイムスタンプを適用できます。

user_properties

 object （省略可）測定のユーザー プロパティ。

user_data

 object （省略可）ユーザー提供データ。
object （省略可）リクエストの同意設定。詳しくは同意セクションをご覧ください。

non_personalized_ads

 boolean 省略可。ユーザーのデータをパーソナライズド広告に使用しないことを示すには、true に設定します。

user_location

 object （省略可）リクエストの地理情報を構造化された形式で設定します。

ip_override

 string （省略可）リクエストの地域情報の取得に使用される IP アドレス。

device

 object 省略可。リクエストのデバイス情報を構造化された形式で設定します。

validation_behavior

 string

省略可。リクエストの検証動作を設定します。

RELAXED または ENFORCE_RECOMMENDATIONS のいずれか。指定しない場合のデフォルトは RELAXED です。

events[]

 array 必須。event アイテムの配列。リクエストごとに最大 25 個のイベントを送信できます。有効なすべてのイベントについては、イベント リファレンスをご覧ください。

events[].name

 string 必須。イベントの名前。すべてのオプションについては、イベントをご覧ください。

events[].params

 object （省略可）イベントのパラメータ。各イベントの推奨パラメータについては、イベントと一般的なイベント パラメータをご覧ください。

共通イベント パラメータ

Measurement Protocol には、次の一般的なイベント パラメータがあります。

キー 型 説明

session_id

 number ユーザー セッションを識別する正の数。いくつかの一般的なユースケースで必要です。正規表現 ^\d+$ と一致する必要があります。

engagement_time_msec

 number イベントのユーザー エンゲージメントの継続時間（ミリ秒単位）。前のイベントからのユーザー エンゲージメント時間を反映する値を使用します。

timestamp_micros

 number イベントの Unix エポック時間（マイクロ秒単位）。このパラメータを使用して、イベントのタイムスタンプをオーバーライドします。

consent 属性は同意のタイプと状態を設定します。consent を指定しない場合、Google アナリティクスでは、対応するクライアントのオンライン インタラクションまたはアプリ インスタンスからの同意設定が使用されます。

キー 型 説明

ad_user_data

 string

（省略可）広告目的でリクエストのイベントとユーザー プロパティから Google にユーザーデータを送信することへの同意。

GRANTED または DENIED のいずれか。

ad_personalization

 string

（省略可）ユーザーのパーソナライズド広告に対する同意。

GRANTED または DENIED のいずれか。

地理情報

user_location 属性と ip_override 属性は、地理情報を提供します。user_location は ip_override より優先されます。

user_location フィールドの構造は次のとおりです。できるだけ多くの属性を指定します。最低でも country_id と region_id をおすすめします。

キー 型 説明

city

 string （省略可）都市の名前。都市が米国にある場合は、country_id と region_id も設定して、Google アナリティクスが都市名を都市 ID に正しくマッピングできるようにします。

region_id

 string （省略可）ISO 3166 の国と区分。たとえば、US-CA、US-AR、CA-BC、GB-LND、CN-HK などです。

country_id

 string （省略可）ISO 3166-1 alpha-2 形式の国。たとえば、US、AU、ES、FR。

subcontinent_id

 string （省略可）UN M49 形式の亜大陸。たとえば、011、021、030、039。

continent_id

 string （省略可）国連 M49 形式の大陸。たとえば、002、019、142、150。

user_location のサンプルを次に示します。

"user_location": {
  "city": "Mountain View",
  "region_id": "US-CA",
  "country_id": "US",
  "subcontinent_id": "021",
  "continent_id": "019"
}

ip_override は user_location の代替手段です。代わりに ip_override を送信すると、Google アナリティクスは IP アドレスから地域情報を取得します。user_location を送信すると、Google アナリティクスは ip_override を無視します。

user_location または ip_override を送信しない場合、Google アナリティクスは client_id。

送信された地理情報に関係なく、Google アナリティクスはプロパティの詳細な位置情報の設定をリクエストに適用します。

デバイス情報

デバイス情報を送信するには、device フィールドを使用します。device フィールドの構造は次のとおりです。できるだけ多くの属性を指定します。最低でも category をおすすめします。

キー 型 説明

category

 string 省略可。デバイスのカテゴリ。たとえば、desktop、tablet、mobile、smart TV。

language

 string 省略可。ISO 639-1 形式の言語。たとえば、en、en-US。

screen_resolution

 string 省略可。デバイスの解像度（WIDTHxHEIGHT 形式）。たとえば、1280x2856、1080x2340。

operating_system

 string 省略可。オペレーティング システムまたはプラットフォーム。例: MacOS

operating_system_version

 string 省略可。オペレーティング システムまたはプラットフォームのバージョン。例: 13.5

model

 string 省略可。デバイスのモデル。例: Pixel 9 Pro、Samsung Galaxy S24。

brand

 string 省略可。デバイスのブランド。例: Google、Samsung。

browser

 string 省略可。ブラウザのブランドまたはタイプ。例: Chrome、Firefox。

browser_version

 string 省略可。ブラウザのバージョン。例: 136.0.7103.60、5.0。

次のスニペットは、device 設定の例を示しています。

"device": {
  "category": "mobile",
  "language": "en",
  "screen_resolution": "1280x2856",
  "operating_system": "Android",
  "operating_system_version": "14",
  "model": "Pixel 9 Pro",
  "brand": "Google",
  "browser": "Chrome",
  "browser_version": "136.0.7103.60"
}

、のいずれを指定した場合でも、Google アナリティクスはプロパティのデバイスデータの詳細設定をリクエストに適用します。

検証動作

validation_behavior 属性は、Measurement Protocol がリクエストの内容を検証する方法を制御します。

  • RELAXED 検証では、形式が正しくないリクエストのみが拒否されます。無効なフィールド名や正しい型ではないデータを含むイベントやパラメータは受け付ける可能性がありますが、上限を超えるパラメータは無視されます。Measurement Protocol では、デフォルトで RELAXED 検証が使用されます。
  • ENFORCE_RECOMMENDATIONS 検証では、型が正しくないイベント パラメータとアイテム パラメータ、または上限を超えるパラメータを含むイベント パラメータとアイテム パラメータは拒否されます。また、ENFORCE_RECOMMENDATIONS は、過去 72 時間以内のタイムスタンプがないイベントまたはユーザー プロパティをすべて拒否します。

次のアプローチをおすすめします。

  • ENFORCE_RECOMMENDATIONS は、イベントを検証する際に、リクエストの潜在的な問題に関するフィードバックをできるだけ多く取得するために使用します。

    リクエストの検証時に ENFORCE_RECOMMENDATIONS を指定するため、イベントビルダーを使用してリクエストを検証することもできます。

  • Measurement Protocol で拒否されるデータを最小限に抑えるため、イベントを送信する際は validation_behavior を指定しないでください。

    特定のリクエストを送信するときにデータ収集よりも厳密な検証を優先する場合は、validation_behavior フィールドを追加して ENFORCE_RECOMMENDATIONS に設定します。

カスタム パラメータ

Measurement Protocol のペイロードには、ユーザー スコープ、イベント スコープ、アイテム スコープのカスタム パラメータを追加できます。

  • ユーザー スコープのカスタム パラメータは user_properties に追加できます。
  • イベント スコープのカスタム パラメータは events[].params に追加できます。
  • アイテム スコープのカスタム パラメータは items に追加できます。

一部のイベントには推奨パラメータがあります。サポートされているすべてのイベントの推奨パラメータについては、イベントをご覧ください。

予約済みの名前

一部のイベント名、パラメータ名、ユーザー プロパティ名は予約済みのため、使用できません。

予約済みのイベント名

以下のイベント名は予約済みのため使用できません。

  • ad_activeview
  • ad_click
  • ad_exposure
  • ad_query
  • ad_reward
  • adunit_exposure
  • app_clear_data
  • app_exception
  • app_install
  • app_remove
  • app_store_refund
  • app_update
  • app_upgrade
  • dynamic_link_app_open
  • dynamic_link_app_update
  • dynamic_link_first_open
  • error
  • firebase_campaign
  • firebase_in_app_message_action
  • firebase_in_app_message_dismiss
  • firebase_in_app_message_impression
  • first_open
  • first_visit
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

また、ad_impression、in_app_purchase、screen_view のイベントはアプリ ストリームでのみ許可されます。

予約済みのパラメータ名

以下のパラメータ名は予約済みのため使用できません。

  • firebase_conversion

パラメータ名の先頭を以下にすることはできません。

  • _ (underscore)
  • firebase_
  • ga_
  • google_
  • gtag.

予約済みのユーザー プロパティ名

以下のユーザー プロパティ名は予約済みのため使用できません。

  • first_open_time
  • first_visit_time
  • last_deep_link_referrer
  • user_id
  • first_open_after_install

また、ユーザー プロパティ名の先頭を以下にすることはできません。

  • _ (underscore)
  • firebase_
  • ga_
  • google_