# Google Analytics Measurement Protocol

> Send server-to-server and offline events to Google Analytics 4 using the Measurement Protocol, with privacy controls built for HIPAA-regulated workflows.

Source: https://docs.oursprivacy.com/docs/google-analytics-measurement-protocol

## Overview

The Google Analytics Measurement Protocol destination allows you to send server-to-server and offline events directly to Google Analytics 4. This is particularly useful for tracking events that occur outside of standard web interactions, such as webhook events, server-side processing, or offline conversions.

**Important Note:** For standard web tracking, we recommend using the [Google Analytics (GA4) destination](https://docs.oursprivacy.com/docs/google-analytics-ga4) instead. The Measurement Protocol destination is specifically designed for server-to-server and offline event tracking scenarios.

## When to Use Measurement Protocol

Use the Google Analytics Measurement Protocol destination when you need to:

* Send events from webhooks or server-side processes
* Track offline conversions or interactions
* Associate server events with existing web sessions
* Send events from devices or systems where standard GA4 tracking isn't available
* Bridge online and offline user behavior

## Setup and Configuration

### Adding Google Analytics Measurement Protocol as a Destination

To add a destination:

1. Navigate to the [Destinations](https://app.oursprivacy.com/destinations) page in your Ours Privacy platform.
2. Click **Add destination** and select **Google Analytics Measurement Protocol** as the destination type.

### Required Configuration

You'll need to provide two key pieces of information:

#### 1. Measurement ID

1. Go to your Google Analytics 4 property
2. Navigate to **Admin** > **Data Streams**
3. Select your web stream
4. Copy the **Measurement ID** (format: `G-XXXXXXXXXX`)

> **Note:** Use a web data stream for events from mobile apps too. If your GA4 property has only app streams, add a web stream to receive Measurement Protocol events. Those events appear under the web stream in your reports.

#### 2. API Secret

1. In the same data stream settings
2. Scroll down to **Measurement Protocol API secrets**
3. Click **Create** to generate a new secret
4. Copy the generated **Secret value**

> **Note:** Sometimes GA4 can truncate your API Secret in the UI. Make sure you are copying over the entire value. The GA4 API Secret is typically **22 characters** in total. Sending an incomplete API Secret will cause dispatches to fail.

## Event Mapping Requirements

When configuring events for the Measurement Protocol destination, you'll be asked to map two critical identifiers:

### Session ID (sid)

The session ID helps Google Analytics associate your events with specific user sessions. Keep the default **SID** mapping, `{{event.default_properties.sid}}`. The Web SDK and the React Native SDK (version 4.1.0 and later) set this session ID on every event.

### Client ID (cid)

The client ID is the unique identifier for a user across sessions. Keep the default **CID** mapping, `{{visitor.cid}}`. Ours Privacy generates a GA4-format client ID for every visitor, including visitors from mobile apps and the Ingest API.

### User ID

This destination does not send a GA4 User-ID. Identifiers you pass to `identify()`, such as `externalId`, stay in Ours Privacy. Event properties are sent as GA4 event parameters, so review your mappings to control what reaches Google.

## Associating Server Events with Web Sessions

To properly associate server events with existing web sessions in Google Analytics, ensure you have a way to link webhook events to existing visitors. This typically involves:

1. **Capturing identifiers from web sessions**: Store the `client_id` and `session_id` from your web tracking
2. **Including these identifiers in server events**: When sending events via webhooks or server-side processes, include the same `client_id` and `session_id`
3. **Mapping in Ours Privacy**: Configure the destination to map these fields correctly

### Example Implementation

When a user completes a web form that triggers a server-side webhook:

```json
// Ours Privacy mapping to associate back to same session id and client id:
{
  "event_name": "form_processed",
  "client_id": "{{visitor.cid}}",
  "session_id": "{{event.default_properties.sid}}"
}
```

## Event Tracking

### Standard and Custom Events

You can send any standard GA4 events or custom events through the Measurement Protocol. Common use cases include:

* **Purchase events**: Track offline purchases or server-processed transactions
* **Lead events**: Track form submissions processed server-side
* **Custom events**: Track any business-specific interactions

### Event Property Limitations

When sending events via Measurement Protocol, please note the following limitations:

* Each event can have a maximum of 20 event properties
* Each event property value must be fewer than 1,000 characters
* Event names are limited to 40 characters
* Event names cannot contain special characters, only underscores are permitted

[See all restrictions here](https://developers.google.com/analytics/devguides/collection/protocol/ga4/sending-events?client_type=gtag)

## Best Practices

1. **Use the standard GA4 destination for web events**: Reserve the Measurement Protocol for server-side and offline events only
2. **Maintain consistent identifiers**: Ensure `client_id` and `session_id` are consistent between web and server events
3. **Send events promptly**: For session attribution, send Measurement Protocol events within 24 hours of the session start
4. **Validate your setup**: Use Google Analytics DebugView to verify events are being received correctly

## Troubleshooting

1. **Remove All Universal Analytics (UA) Scripts**

   Google no longer supports Universal Analytics (UA). Remove all UA scripts before installing Ours Privacy.

2. **Remove GA4 Tracking for the Account Connect via Ours Privacy**

   Since Ours Privacy automatically tracks page views and other events, you must remove any existing GA4 tracking scripts for the specific account connected to Ours Privacy to prevent duplicate event counts.

3. **Consider Removing Other GA4 Accounts**

   If you have multiple GA4 accounts on the same page, we recommend removing them as well. This reduces the chance of conflicts and increases the compliance of your website.

4. **Confirm correct inbound payload structure**

   Reference the inbound payload structure and ensure that the event name and any other inbound parameters are being mapped over correctly. An invalid or exempt event name will cause the dispatch to fail.

5. **Ensure the API Secret and Measurement ID are correct**

   Dispatching an incorrect Measurement ID or API Secret will cause dispatches to fail.

6. **Make sure mappings are set up correctly**

   The only requirements for this destination to work is that the API Secret and Measurement ID are correct, the event name is present and valid, and that the CID and SID are mapped correctly as noted above: `{{visitor.cid}}` and `{{event.default_properties.sid}}`.
