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.

firebase_app_id

 Required. Firebase App ID. The identifier for a Firebase app. Found in the Firebase console under:
Project Settings > General > Your Apps > App ID

JSON post body

Key Type Description

app_instance_id

 string

Required. Uniquely identifies a specific installation of a Firebase app. This value needs to be retrieved through the Firebase SDK.

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.

user_data

 object Optional. User-provided data. See the user-provided data guide for more information.
object Optional. Sets the consent settings for the request. See the consent section for more information.

non_personalized_ads

 boolean Optional. Set to true to indicate the user's data 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.

The consent attribute configures consent types and states. If you don't specify consent, then Google Analytics will use the consent settings from corresponding online interactions for the client or app instance.

Key Type Description

ad_user_data

 string

Optional. Sets consent for sending user data from the request's events and user properties to Google for advertising purposes.

Must be either GRANTED or DENIED.

ad_personalization

 string

Optional. Sets consent for personalized advertising for the user.

Must be either GRANTED or DENIED.

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_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
  • 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_