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 a tutorial_begin event to your Google Analytics server:

const measurement_id = `G-XXXXXXXXXX`;
const api_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: {},
    }]
  })
});

Override timestamp

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

The timestamp_micros of the event.
The timestamp_micros of the request.
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.