Try the MCP server for Google Analytics. Install from GitHub, and see the announcement for more details.

Send Measurement Protocol events to Google Analytics

AI-generated Key Takeaways

This guide details sending Google Analytics Measurement Protocol web and app stream events to a Google Analytics server to view them in reports.
To send an event, use an HTTP POST request to the specified endpoint with the correct host and a JSON body containing the event data.
The request URL requires an api_secret generated in the Google Analytics UI and a firebase_app_id found in the Firebase console.
The request body must be in JSON format and include an app_instance_id and an array of events.
Timestamping for events and user properties follows a specific hierarchy, and events can be backdated up to 72 hours with validation behavior options for older data.
There are limitations on the number of events, parameters, user properties, and character lengths for names and values, as well as a maximum post body size.

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 collection and modification > Data streams > choose your stream > Measurement Protocol API secrets > Create.

firebase_app_id: The Firebase App ID, found in the Firebase console under Project Settings > General > Your Apps > App ID.

The firebase_app_id isn't the same as the app_instance_id. The firebase_app_id identifies your app, whereas app_instance_id identifies a single installation of the app.

You must provide a request body in the JSON POST body format for the Measurement Protocol. Here's an example:

  {
   "app_instance_id": "APP_INSTANCE_ID",
   "events": [
      {
        "name": "login",
        "params": {
          "method": "Google",
          "session_id": "SESSION_ID",
          "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, includes geographic information using the user_location field, and includes device information using the device field.

const firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_ID",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 150
        }
      }
    ],
    user_location: {
      city: "Mountain View",
      region_id: "US-CA",
      country_id: "US",
      subcontinent_id: "021",
      continent_id: "019"
    },
    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"
    }
  })
});

The format of firebase_app_id is platform specific. See Application ID under Firebase config files and objects.

Override timestamp

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

The timestamp_micros of the event or user property.
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 and user properties in the request. As a result, the Measurement Protocol assigns a timestamp of requestUnixEpochTimeInMicros to the tutorial_begin and join_group events and the customer_tier user property.

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

The following example sends a request-level timestamp, an event-level timestamp, and a user property-level timestamp. As a result, the Measurement Protocol assigns the following timestamps:

tutorialBeginUnixEpochTimeInMicros for the tutorial_begin event
customerTierUnixEpochTimeInMicros for the customer_tier user property
requestUnixEpochTimeInMicros for the join_group event and the newsletter_reader user property.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM",
      "timestamp_micros": customerTierUnixEpochTimeInMicros
    },
    "newsletter_reader": {
      "value": "true"
    }
  }
}

Validation behavior for past events and user properties

Events and user properties can be backdated up to 72 hours. If the timestamp_micros value is earlier than 72 hours ago, the Measurement Protocol accepts or rejects the event or user property as follows:

If the validation_behavior is not set or is set to RELAXED, the Measurement Protocol accepts the event or user property but overrides its timestamp to 72 hours ago.
If the validation_behavior is set to ENFORCE_RECOMMENDATIONS, the Measurement Protocol rejects the event or user property.

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 alphanumeric characters and underscores, and must start with an alphabetic character.
Parameter names including item parameters must be 40 characters or fewer, can only contain alphanumeric 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.
The timestamp must be within the last 72 hours. See Validation behavior for past events for details.
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.