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 HTTP POST request:

POST https://www.google-analytics.com/mp/collect
payload_data
  • payload_data

    The BODY of the request. The body should be JSON. 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.

measurement_id

Measurement ID. The identifier for a Data Stream. Found in the Google Analytics UI under:
Admin > Data Streams > choose your stream > Measurement ID >

JSON post body

Key Type Description

client_id

string

Required. Uniquely identifies a user instance of a web client. See send event to the Measurement Protocol.

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 48 hours.

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.

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
  • adunit_exposure
  • app_clear_data
  • app_install
  • app_update
  • app_remove
  • error
  • first_open
  • first_visit
  • in_app_purchase
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • 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:

  • google_
  • ga_
  • firebase_

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:

  • google_
  • ga_
  • firebase_