Measurement Protocol reference

AI-generated Key Takeaways

outlined_flag

• Data for the Measurement Protocol must be sent securely using HTTPS POST requests to a specified endpoint.

• The payload for a Measurement Protocol request consists of query parameters, including a required api_secret, and a JSON POST body with various optional and required fields like user_id, timestamp_micros, and events.

• The events array within the JSON body is required and can contain up to 25 event items, each needing a name and optionally including params.

• Common event parameters like session_id and engagement_time_msec are important for user activity to display in reports like Realtime.

• The Measurement Protocol uses RELAXED validation by default, but ENFORCE_RECOMMENDATIONS can be used for stricter validation, particularly when validating events.

This page describes the transport mechanism and data parameters for the Measurement Protocol.

Transport

All data must be sent securely using HTTPS POST requests.

Send requests to the following endpoint:

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

If you want your data to be collected in the EU, use the following endpoint instead:

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

Here's a sample POST request:

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

Replace PAYLOAD_DATA with Payload of the request.

The Measurement Protocol returns a 2xx status code if the HTTP request is received. The Measurement Protocol doesn't return an error code if the payload is malformed, or if the data is incorrect or not processed by Google Analytics.

Payload

The payload has two parts:

1. Query parameters.
2. A JSON POST body.

Query parameters

JSON POST body

Common event parameters

The Measurement Protocol has the following common event parameters:

Consent

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

Geographic information

The user_location and ip_override attributes provide geographic information. user_location takes precedence over ip_override.

Here's the structure of the user_location field. Provide as many of the attributes as possible. We recommend country_id and region_id at a minimum.

Here's a sample user_location:

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

ip_override is an alternative to user_location. If you send ip_override instead, Google Analytics derives geographic information from the IP address. If you send user_location, Google Analytics ignores ip_override.

If you don't send user_location or ip_override, Google Analytics derives geographic information from tagging events using client_id.

Google Analytics applies the property's granular location data settings to the request, regardless of the geographic information sent.

Device information

To send device information, use the device field. Here's the structure of the device field. Provide as many of the attributes as possible. We recommend category at a minimum.

The following snippet shows an example of device settings:

"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"
}

Regardless of whether you specify Google Analytics applies the property's granular device data settings to the request.

Validation behavior

The validation_behavior attribute controls how the Measurement Protocol validates the contents of the request.

• RELAXED validation only rejects requests that are malformed. It might still accept events and parameters with invalid field names or with data that isn't the correct type, but it ignores parameters that exceed limits. The Measurement Protocol uses RELAXED validation by default.
• ENFORCE_RECOMMENDATIONS validation rejects event and item parameters that aren't the correct type or that contain parameters that exceed limits. In addition, ENFORCE_RECOMMENDATIONS rejects any event or user property with a timestamp more than 3 business days in the past in the property's time zone.

We recommend the following approach:

• Use ENFORCE_RECOMMENDATIONS when you validate events to get as much feedback as possible about potential problems with your requests.

  You can also validate requests using the Event Builder since it specifies ENFORCE_RECOMMENDATIONS when validating requests.

• Don't specify validation_behavior when you send events to minimize the data rejected by the Measurement Protocol.

  If you want to prioritize strict validation over data collection when sending a particular request, add the validation_behavior field and set it to ENFORCE_RECOMMENDATIONS.

Custom parameters

You can include custom user-scoped, event-scoped and item-scoped parameters in a Measurement Protocol payload.

• User-scoped custom parameters can be included in user_properties.
• Event-scoped custom parameters can be included in events[].params.
• Item-scoped custom parameters can be included in items.

Recommended values for certain events

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

Reserved names

Some event, parameter, and user property names are reserved and can't be used:

Reserved event names

The following event names are reserved and can't 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 can't be used:

• firebase_conversion

Parameter names can't begin with the following:

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

Reserved user property names

The following user property names are reserved and can't be used:

• first_open_time
• first_visit_time
• last_deep_link_referrer
• user_id
• first_open_after_install

Additionally, user property names can't begin with:

• _ (underscore)
• firebase_
• ga_
• google_