GA4 Measurement Protocol

GA4 Measurement Protocol

Complete guide to GA4 Measurement Protocol for server-side event tracking.

Overview

The GA4 Measurement Protocol allows server-side event collection, enabling data transmission to GA4 from any HTTP-capable environment including backend servers, mobile app backends, kiosks, and IoT devices.

When to Use Measurement Protocol

API Endpoints

Production Endpoint

POST https://www.google-analytics.com/mp/collect

Debug Endpoint

POST https://www.google-analytics.com/debug/mp/collect

Key Difference: Debug returns validation messages without storing data.

Authentication

Required Credentials

1. Measurement ID (G-XXXXXXXXXX)

   • Location: GA4 Admin -> Data Streams -> Web Stream

2. API Secret

   • Location: Data Streams -> Measurement Protocol API secrets

Generating API Secret

1. GA4 Admin -> Data Streams
2. Click your data stream
3. Scroll to "Measurement Protocol API secrets"
4. Click "Create"
5. Enter nickname (e.g., "Server-side tracking")
6. Click "Create"
7. Copy secret immediately (shown once only)
8. Store securely

Request Structure

URL Format

https://www.google-analytics.com/mp/collect?measurement_id={MEASUREMENT_ID}&api_secret={API_SECRET}

Headers

Content-Type: application/json

Request Body (JSON)

{
  "client_id": "unique_client_identifier",
  "user_id": "optional_user_id",
  "timestamp_micros": "1234567890123456",
  "user_properties": {
    "property_name": {
      "value": "property_value"
    }
  },
  "consent": {
    "ad_storage": "granted",
    "analytics_storage": "granted"
  },
  "events": [
    {
      "name": "event_name",
      "params": {
        "parameter_name": "parameter_value",
        "value": 123.45,
        "currency": "USD"
      }
    }
  ]
}

Required and Optional Fields

Required Fields

Optional Fields

Common Event Parameters

Implementation Examples

Python Implementation

Using Requests Library:

import requests
import json
import uuid

MEASUREMENT_ID = "G-XXXXXXXXXX"
API_SECRET = "your_api_secret"
ENDPOINT = f"https://www.google-analytics.com/mp/collect?measurement_id={MEASUREMENT_ID}&api_secret={API_SECRET}"

def send_event(client_id, event_name, params=None):
    payload = {
        "client_id": client_id,
        "events": [{
            "name": event_name,
            "params": params or {}
        }]
    }

    response = requests.post(
        ENDPOINT,
        headers={"Content-Type": "application/json"},
        data=json.dumps(payload)
    )

    return response.status_code == 204

# Send page view
send_event(
    client_id="user_123.session_456",
    event_name="page_view",
    params={
        "page_location": "https://example.com/page",
        "page_title": "Example Page"
    }
)

# Send purchase
send_event(
    client_id="user_123.session_456",
    event_name="purchase",
    params={
        "transaction_id": "T_12345",
        "value": 99.99,
        "currency": "USD",
        "items": [{
            "item_id": "SKU_123",
            "item_name": "Product Name",
            "price": 99.99,
            "quantity": 1
        }]
    }
)

Using ga4mp Library:

# Install: pip install ga4mp
from ga4mp import GtagMP

ga = GtagMP(
    measurement_id="G-XXXXXXXXXX",
    api_secret="your_api_secret",
    client_id="unique_client_id"
)

# Send event
ga.send_event(
    event_name="purchase",
    event_parameters={
        "transaction_id": "T_12345",
        "value": 99.99,
        "currency": "USD",
        "items": [{
            "item_id": "SKU_123",
            "item_name": "Product Name",
            "price": 99.99,
            "quantity": 1
        }]
    }
)

Node.js Implementation

const axios = require('axios');
const { v4: uuidv4 } = require('uuid');

const MEASUREMENT_ID = 'G-XXXXXXXXXX';
const API_SECRET = 'your_api_secret';
const ENDPOINT = `https://www.google-analytics.com/mp/collect?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`;

async function sendEvent(clientId, eventName, params = {}) {
  const payload = {
    client_id: clientId,
    events: [{
      name: eventName,
      params: params
    }]
  };

  try {
    const response = await axios.post(ENDPOINT, payload, {
      headers: { 'Content-Type': 'application/json' }
    });
    return response.status === 204;
  } catch (error) {
    console.error('Error sending event:', error);
    return false;
  }
}

// Send purchase event
sendEvent('client_123', 'purchase', {
  transaction_id: 'T_12345',
  value: 99.99,
  currency: 'USD',
  items: [{
    item_id: 'SKU_123',
    item_name: 'Product',
    price: 99.99,
    quantity: 1
  }]
});

PHP Implementation

<?php
// Using php-GA4-Measurement-Protocol library
// Install: composer require br33f/php-ga4-measurement-protocol

use Br33f\Ga4\MeasurementProtocol\Dto\Event\PurchaseEvent;
use Br33f\Ga4\MeasurementProtocol\Dto\Request\MeasurementRequest;
use Br33f\Ga4\MeasurementProtocol\Service;

$measurementId = 'G-XXXXXXXXXX';
$apiSecret = 'your_api_secret';

$service = new Service($apiSecret, $measurementId);

$event = new PurchaseEvent();
$event->setTransactionId('T_12345')
      ->setValue(99.99)
      ->setCurrency('USD');

$request = new MeasurementRequest();
$request->setClientId('unique_client_id')
        ->addEvent($event);

$service->send($request);
?>

cURL Example

curl -X POST "https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_SECRET" \
-H "Content-Type: application/json" \
-d '{
  "client_id": "client_123",
  "events": [{
    "name": "purchase",
    "params": {
      "transaction_id": "T_12345",
      "value": 99.99,
      "currency": "USD"
    }
  }]
}'

Validation with Debug Endpoint

Send to Debug Endpoint

curl -X POST "https://www.google-analytics.com/debug/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_SECRET" \
-H "Content-Type: application/json" \
-d '{
  "client_id": "test_client",
  "events": [{
    "name": "test_event",
    "params": {
      "test_param": "test_value"
    }
  }]
}'

Response Format

{
  "validationMessages": [
    {
      "fieldPath": "events[0].name",
      "description": "Event name must be 40 characters or fewer",
      "validationCode": "NAME_INVALID"
    }
  ]
}

Empty Response = Valid

• No validationMessages = payload valid
• Status 200 = request processed
• Production returns 204 (no content)

Validation Codes

Best Practices

1. Always Validate First

DEBUG_ENDPOINT = f"https://www.google-analytics.com/debug/mp/collect?measurement_id={MEASUREMENT_ID}&api_secret={API_SECRET}"

def validate_event(payload):
    response = requests.post(
        DEBUG_ENDPOINT,
        headers={"Content-Type": "application/json"},
        data=json.dumps(payload)
    )
    return response.json()

2. Use Consistent client_id

• Same user = same client_id across sessions
• Store in database for logged-in users
• Use UUID format for anonymity

3. Include session_id

• Maintain session continuity
• Generate unique session ID
• Keep consistent within session

4. Batch Events

payload = {
    "client_id": "client_123",
    "events": [
        {"name": "event_1", "params": {}},
        {"name": "event_2", "params": {}},
        {"name": "event_3", "params": {}}
    ]  # Up to 25 events per request
}

5. Handle Errors Gracefully

def send_with_retry(payload, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(ENDPOINT, json=payload)
            if response.status_code == 204:
                return True
        except Exception as e:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
            else:
                log_error(e, payload)
    return False

6. Set Proper Timestamps

import time

# For historical data (max 3 days past)
timestamp_micros = int(time.time() * 1_000_000)

payload = {
    "client_id": "client_123",
    "timestamp_micros": str(timestamp_micros),
    "events": [...]
}

7. Respect Consent

payload = {
    "client_id": "client_123",
    "consent": {
        "ad_storage": "denied",
        "analytics_storage": "granted"
    },
    "events": [...]
}

Limits

Common Issues

Events Not Appearing

Causes:

• Wrong Measurement ID
• Invalid API secret
• Validation errors
• Consent blocking

Solutions:

1. Validate with debug endpoint
2. Verify credentials
3. Check consent parameters

Duplicate Events

Causes:

• Same request sent multiple times
• Missing deduplication logic

Solutions:

1. Implement idempotency
2. Track sent events
3. Use unique transaction IDs

Missing User Association

Cause: Different client_id values

Solution: Store and reuse client_id from frontend

Quick Reference

Endpoint

Production: /mp/collect
Debug: /debug/mp/collect

Required Fields

• client_id (UUID recommended)
• events array
• event name

Max Limits

• 25 events per request
• 40 characters per event name
• 25 parameters per event
• 25 user properties per request

Validation

• Send to debug endpoint
• Empty response = valid
• Check validationMessages array