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

Note: All data must be sent securely via HTTPS.

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.

Important: If you do not get a 2xx status code, you should not retry the request. Instead, you should stop and correct any errors in your HTTP request.

Payload

Firebase gtag.js

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. user_id may only include utf-8 characters.
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. This value should be in microseconds, not milliseconds.
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.
consent	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. Obsolete: Use the ad_personalization field of consent instead of this field. Google Analytics accepts either field, but ad_personalization is recommended.
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.

Consent

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.

Recommended values for certain events

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_