Send Measurement Protocol events to Google Analytics

Page Summary

outlined_flag

• 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.

The identifiers and parameters required for Measurement Protocol requests depend on whether you are sending events to a Web stream or an App stream.

• For Web streams (typically instrumented with gtag.js or Google Tag Manager), you use the measurement_id in the request URL and the client_id in the JSON body to identify the user instance. The client_id should match the ID generated by the Google Analytics tag on your website.
• For App streams (instrumented with the Firebase SDK), you use the firebase_app_id in the request URL and the app_instance_id in the JSON body, which are provided by the Google Analytics for Firebase SDK.

This guide provides examples for both scenarios.

Key request components by stream type

Choose the platform you want to see in this guide:

This tab shows instructions for sending events from your server that correlate with user activity in an App stream using the Google Analytics for Firebase SDK. Keep in mind that these requests use firebase_app_id and app_instance_id.

Prerequisites

To send events using the Measurement Protocol, you need specific identifiers from your Google Analytics property or Firebase project.

API secret

The api_secret is used to authenticate your requests. It is crucial to keep this secret confidential.

To create a new secret:

1. Go to Google Analytics and navigate to your account and property.
2. Click Admin in the lower left.
3. Under Data collection and modification, click Data streams.
4. Select your Web or App data stream.
5. Click Measurement Protocol API secrets.
6. Click Create.
7. Enter a nickname for the secret and click Create.

8. Copy the Secret value.

Firebase app ID

The firebase_app_id identifies your Firebase app. It is not the same as the app_instance_id.

To find your Firebase App ID:

1. Open your project in the Firebase console.
2. Click the settings gear icon next to Project Overview and select Project settings.
3. Under the General tab, go to the Your apps section.
4. Select the specific iOS or Android app.
5. Copy the App ID value.

Format the request

The Google Analytics Measurement Protocol only supports HTTP POST requests.

To send an event, use the following format:

POST /mp/collect?firebase_app_id=<var>FIREBASE_APP_ID</var>&api_secret=<var>API_SECRET</var> HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

You must provide the following in the request URL query parameters (see Prerequisites for details on how to find or create these values):

• api_secret: The API secret to authenticate the request.
• firebase_app_id: The Firebase App ID of your application.

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

You must provide app_instance_id in the request body to identify a unique installation of your mobile app. Note that this is different from the firebase_app_id which identifies the app itself. For more information on the app_instance_id and how to retrieve it using the Firebase SDK, see the app_instance_id reference documentation.

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",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_ID",
    events: [
      {
        name: "tutorial_begin",
        params: {