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 Measurement Protocol for Google Analytics 4 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.

  • 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: {},
    }]
  })
});

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.
  • Item parameters can have a maximum of 10 custom parameters.
  • The post body must be smaller than 130kB.
  • Event-level attribution from Measurement Protocol events is supported up to 63 days after the most recent tagging online event for conversion export to Ads and other media integrations, even if the conversion window for the conversion event is greater than 63 days. In contrast, event-level attribution for tagging online events is supported for the entire conversion window.
  • For remarketing purposes, you can join Measurement Protocol events up to the following number of days after the most recent online event with an associated cookie or device ID:
    • Web stream: 30 days
    • App stream: 42 days
  • App Measurement Protocol events sent to Google Analytics 4 don't populate Search audiences in Google Ads for app users.