Measurement Protocol Reference

Overview

There are two parts to sending data to Google Analytics using the Measurement Protocol:

  1. The transport - where and how you send data
  2. The payload - the data you send

This document describes how the transport and payload are formatted.

Transport

URL endpoint

You send data using the Measurement Protocol by making HTTP POST requests to the following endpoint:

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

To send an event, issue the following POST request:

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

  • The BODY of the request. See Payload.

Response codes

The Measurement Protocol always returns a 2xx status code if the HTTP request was received. The Measurement Protocol does not return an error code if the payload data was malformed, or if the data in the payload was incorrect or was not processed by Google Analytics.

Payload

Data is sent to Google Analytics using the Measurement Protocol Data in two parts:

  1. Query parameters
  2. A JSON POST body

query parameters

Parameter Name Description

api_secret

Required. An API Secret that is generated through the Google Analytics UI.

To create a new secret, navigate in the Google Analytics UI to:
Admin > Data Streams > choose your stream > Measurement Protocol > Create

We recommend that you keep these private to your organization. If you deploy the measurement protocol client-side, you should regularly rotate api_secrets to avoid excessive SPAM.

JSON post body

Key Type Description

user_id

 string

Optional. A unique identifier for a user. See User-ID for cross-platform analysis for more information on this identifier.

timestamp_micros

 number

Optional. A Unix timestamp (in microseconds) for the time to associate with the event. This should only be set to record events that happened in the past. This value can be overridden via user_property or event timestamps. Events can be backdated up to 3 calendar days based on the property's timezone.

user_properties

 object Optional. The user properties for the measurement. See User properties for more information.

non_personalized_ads

 boolean Optional. Set to true to indicate these events should not be used for personalized ads.

events[]

 array Required. An array of event items. Up to 25 events can be sent per request. See the events reference for all valid events.

events[].name

 string Required. The name for the event. See the events reference for all options.

events[].params

 object Optional. The parameters for the event. See events for the suggested parameters for each event.

Custom parameters

In addition to the prescribed parameters, you can include custom user-scoped, event-scoped and item-scoped parameters inside a Measurement Protocol payload.

  • User-scoped custom parameters can be included in the user_properties object of the payload.
  • Event-scoped custom parameters can be included in events[].params object of the payload.
  • Item-scoped custom parameters can be included in the items array for each event.

Some events have recommended parameters. See events for the recommended parameters for all supported events.

Reserved names

Reserved event names

The following event names are reserved and cannot be used:

  • ad_activeview
  • ad_click
  • ad_exposure
  • ad_impression
  • 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
  • in_app_purchase
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • screen_view
  • session_start
  • user_engagement

Reserved parameter names

The following parameter names are reserved and cannot be used:

  • firebase_conversion

Additionally, parameter names cannot begin with:

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

Reserved user property names

The following user property names are reserved and cannot be used:

  • first_open_time
  • first_visit_time
  • last_deep_link_referrer
  • user_id
  • first_open_after_install

Additionally, user property names cannot begin with:

  • _ (underscore)
  • firebase_
  • ga_
  • google_