Send Measurement Protocol events to Google Analytics

This guide explains how you can send Google Analytics Measurement Protocol web and app stream events to a Google Analytics server, so that you can view Measurement Protocol events in your Google Analytics reports.

Choose the platform you want to see in this guide:

Format the request

The Google Analytics Measurement Protocol only supports HTTP POST requests.

To send an event, use the following format:

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

You must provide the following in the request URL:

  • api_secret: The API SECRET generated in the Google Analytics UI.

    To create a new secret, navigate to Admin > Data Streams > choose your stream > Measurement Protocol > Create.

  • measurement_id: The measurement ID associated with a stream, found in the Google Analytics UI under Admin > Data Streams > choose your stream > Measurement ID.

    The measurement_id isn't your Stream ID.

See query parameters for the full reference.

You must provide the following in the request body:

  • client_id: A unique identifier for a client. This is different than a Firebase app_instance_id. Use gtag.js('get').

  • user_id: Optional. A unique identifier for a user. Can only contain UTF-8 characters. See User-ID for cross-platform analysis for more information about this identifier.

  • consent: Optional. Learn how to set consent settings.

  • timestamp_micros: Optional. The Unix epoch time, in microseconds, for the events and user properties in the request. If not specified, defaults to the time of the request.

  • events: An array of event items. You can include multiple events in one request.

    In order for user activity to display in reports like Realtime, engagement_time_msec and session_id must be supplied as part of the params for an event. The engagement_time_msec parameter should reflect the event's engagement time in milliseconds.

    Here's an example:

{"client_id":"123456.7654321","events":[{"name":"campaign_details","params":{"campaign_id":"google_1234","campaign":"Summer_fun","source":"google","medium":"cpc","term":"summer+travel","content":"logolink","session_id":"123","engagement_time_msec":100}}]}

While session_start is a reserved event name, creating a new session_id creates a new session without the need to send session_start. Understand how sessions are counted.

Try it

Here's an example you can use to send multiple events at once. This example sends a tutorial_begin event and a join_group event to your Google Analytics server.

constmeasurement_id=`G-XXXXXXXXXX`;constapi_secret=`<secret_value>`;fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`,{method:"POST",body:JSON.stringify({client_id:"XXXXXXXXXX.YYYYYYYYYY",events:[{name:"tutorial_begin",params:{"session_id":"123","engagement_time_msec":100}},{name:"join_group",params:{"group_id":"G_12345","session_id":"123","engagement_time_msec":150}}]})});

Override timestamp

The Measurement Protocol uses the first timestamp it finds in the following list for each event in the request:

  1. The timestamp_micros of the event.
  2. The timestamp_micros of the request.
  3. The time that the Measurement Protocol receives the request.

The following example sends a request-level timestamp that applies to all of the events in the request. As a result, the Measurement Protocol assigns both the tutorial_begin and join_group events a timestamp of requestUnixEpochTimeInMicros.

{"timestamp_micros":requestUnixEpochTimeInMicros,"events":[{"name":"tutorial_begin"},{"name":"join_group","params":{"group_id":"G_12345",}}]}

The following example sends both a request-level timestamp and an event-level timestamp. As a result, the Measurement Protocol assigns the tutorial_begin event a timestamp of tutorialBeginUnixEpochTimeInMicros, and the join_group event a timestamp of requestUnixEpochTimeInMicros.

{"timestamp_micros":requestUnixEpochTimeInMicros,"events":[{"name":"tutorial_begin","timestamp_micros":tutorialBeginUnixEpochTimeInMicros},{"name":"join_group","params":{"group_id":"G_12345",}}]}

Limitations

The following limitations apply to sending Measurement Protocol events to Google Analytics:

  • Requests can have a maximum of 25 events.
  • Events can have a maximum of 25 parameters.
  • Events can have a maximum of 25 user properties.
  • User property names must be 24 characters or fewer.
  • User property values must be 36 characters or fewer.
  • Event names must be 40 characters or fewer, can only contain alpha-numeric characters and underscores, and must start with an alphabetic character.
  • Parameter names including item parameters must be 40 characters or fewer, can only contain alpha-numeric characters and underscores, and must start with an alphabetic character.
  • Parameter values including item parameter values must be 100 characters or fewer for a standard Google Analytics property, and 500 characters or fewer for a Google Analytics 360 property.
  • Item parameters can have a maximum of 10 custom parameters.
  • The post body must be smaller than 130kB.
  • App Measurement Protocol events sent to Google Analytics don't populate Search audiences in Google Ads for app users.

For additional requirements of each use case, see common use cases.