Initial commit
This commit is contained in:
Zhongwei Li
408
skills/ga4-measurement-protocol/SKILL.md
Normal file
408
skills/ga4-measurement-protocol/SKILL.md
Normal file
@@ -0,0 +1,408 @@
|
||||
---
|
||||
name: ga4-measurement-protocol
|
||||
description: Complete guide to GA4 Measurement Protocol for server-side event tracking including API authentication, request format, validation, and implementation examples. Use when implementing server-side tracking, sending events from backend, working with Measurement Protocol API, integrating CRM with GA4, or tracking offline conversions. Covers API secrets, debug endpoint, Python/Node.js/PHP examples, and rate limits.
|
||||
---
|
||||
|
||||
# GA4 Measurement Protocol
|
||||
|
||||
## Overview
|
||||
|
||||
The GA4 Measurement Protocol allows server-side event collection, enabling data transmission to GA4 from any HTTP-capable environment including backend servers, mobile apps, kiosks, and IoT devices.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Invoke this skill when:
|
||||
|
||||
- Implementing server-side event tracking
|
||||
- Sending events from backend/server environments
|
||||
- Tracking offline conversions or transactions
|
||||
- Integrating CRM systems with GA4
|
||||
- Sending events from mobile app backends
|
||||
- Tracking server-to-server transactions
|
||||
- Implementing purchase tracking from payment processors
|
||||
- Tracking subscription renewals or recurring payments
|
||||
- Sending lead generation events from forms backend
|
||||
- Implementing custom server-side analytics
|
||||
- Working with headless CMS or API-first architectures
|
||||
- Debugging Measurement Protocol requests
|
||||
- Validating event payloads before production
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
### API Endpoints
|
||||
|
||||
**Production Endpoint:**
|
||||
```
|
||||
POST https://www.google-analytics.com/mp/collect
|
||||
```
|
||||
|
||||
**Debug Endpoint (Validation):**
|
||||
```
|
||||
POST https://www.google-analytics.com/debug/mp/collect
|
||||
```
|
||||
|
||||
**Key Difference:** Debug endpoint returns validation messages without storing data.
|
||||
|
||||
### Authentication Requirements
|
||||
|
||||
**Two Credentials Required:**
|
||||
|
||||
1. **Measurement ID** (format: `G-XXXXXXXXXX`)
|
||||
- Find in: GA4 Admin → Data Streams → Web Stream details
|
||||
|
||||
2. **API Secret**
|
||||
- Generate in: Data Streams → Measurement Protocol API secrets → Create
|
||||
|
||||
**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** (cannot retrieve later)
|
||||
|
||||
### Request Structure
|
||||
|
||||
**URL Format:**
|
||||
```
|
||||
https://www.google-analytics.com/mp/collect?measurement_id={MEASUREMENT_ID}&api_secret={API_SECRET}
|
||||
```
|
||||
|
||||
**Headers:**
|
||||
```
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Body (JSON):**
|
||||
```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 Fields
|
||||
|
||||
- **client_id**: Unique identifier for client (UUID recommended)
|
||||
- **events**: Array of event objects (max 25 events per request)
|
||||
- **events[].name**: Event name (string, ≤40 characters)
|
||||
|
||||
### Optional Fields
|
||||
|
||||
- **user_id**: User identifier for cross-device tracking
|
||||
- **timestamp_micros**: Event timestamp in microseconds (UTC)
|
||||
- **user_properties**: User-level properties
|
||||
- **consent**: Consent status (ad_storage, analytics_storage)
|
||||
|
||||
### Common Event Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `session_id` | string | Session identifier |
|
||||
| `engagement_time_msec` | integer | Engagement time in milliseconds |
|
||||
| `page_location` | string | Full URL |
|
||||
| `page_title` | string | Page title |
|
||||
| `value` | number | Monetary value |
|
||||
| `currency` | string | ISO 4217 currency code (USD, EUR) |
|
||||
| `transaction_id` | string | Unique transaction ID |
|
||||
| `items` | array | E-commerce items array |
|
||||
|
||||
### Python Implementation
|
||||
|
||||
**Using Requests Library:**
|
||||
|
||||
```python
|
||||
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(event_name, params=None):
|
||||
payload = {
|
||||
"client_id": str(uuid.uuid4()),
|
||||
"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("page_view", {
|
||||
"page_location": "https://example.com/page",
|
||||
"page_title": "Example Page"
|
||||
})
|
||||
|
||||
# Send purchase
|
||||
send_event("purchase", {
|
||||
"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:**
|
||||
|
||||
```python
|
||||
# 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
|
||||
|
||||
```javascript
|
||||
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(eventName, params = {}) {
|
||||
const payload = {
|
||||
client_id: uuidv4(),
|
||||
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('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
|
||||
<?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);
|
||||
?>
|
||||
```
|
||||
|
||||
### Validation with Debug Endpoint
|
||||
|
||||
**Send to Debug Endpoint:**
|
||||
|
||||
```bash
|
||||
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:**
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
### Validation Codes
|
||||
|
||||
| Code | Description | Fix |
|
||||
|------|-------------|-----|
|
||||
| `NAME_INVALID` | Invalid event/parameter name | Use lowercase, underscores, ≤40 chars |
|
||||
| `NAME_RESERVED` | Reserved name used | Check GA4 reserved names list |
|
||||
| `VALUE_INVALID` | Invalid parameter value | Check data type, format |
|
||||
| `VALUE_REQUIRED` | Required value missing | Add required parameter |
|
||||
| `VALUE_OUT_OF_BOUNDS` | Value exceeds limits | Check numeric ranges |
|
||||
| `EXCEEDED_MAX_ENTITIES` | Too many events | Max 25 events per request |
|
||||
|
||||
### Best Practices
|
||||
|
||||
1. **Always Validate First:**
|
||||
- Use debug endpoint before production
|
||||
- Test with sample data
|
||||
- Verify response is empty (valid)
|
||||
|
||||
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:**
|
||||
- Send up to 25 events per request
|
||||
- More efficient than individual requests
|
||||
- Reduces API calls
|
||||
|
||||
5. **Handle Errors Gracefully:**
|
||||
- Implement retry logic with exponential backoff
|
||||
- Log failed requests
|
||||
- Queue events for retry
|
||||
|
||||
6. **Set Proper Timestamps:**
|
||||
- Use `timestamp_micros` for historical data
|
||||
- Convert to microseconds: `timestamp_ms * 1000`
|
||||
- Max 3 days in past, 72 hours in future
|
||||
|
||||
7. **Respect Consent:**
|
||||
- Set consent parameters appropriately
|
||||
- Match frontend consent status
|
||||
- Required for GDPR compliance
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
- **ga4-setup** - Initial GA4 property and data stream setup
|
||||
- **ga4-debugview** - Testing Measurement Protocol events in DebugView
|
||||
- **ga4-recommended-events** - Sending recommended event structures
|
||||
- **ga4-custom-events** - Server-side custom event implementation
|
||||
- **ga4-user-tracking** - Implementing User ID server-side
|
||||
- **ga4-privacy-compliance** - Setting consent parameters correctly
|
||||
- **ga4-bigquery** - Analyzing server-side events in BigQuery
|
||||
|
||||
## References
|
||||
|
||||
- **references/measurement-protocol-complete.md** - Full API reference and examples
|
||||
- **references/authentication-setup.md** - API secrets and authentication guide
|
||||
- **references/event-validation.md** - Validation patterns and troubleshooting
|
||||
- **references/implementation-examples.md** - Real-world implementation patterns (Python, Node.js, PHP)
|
||||
- **references/rate-limits-best-practices.md** - Rate limits, batching, and optimization
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**Generate API Secret:**
|
||||
Admin → Data Streams → Measurement Protocol API secrets → Create
|
||||
|
||||
**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 event parameters per event
|
||||
- 25 user properties per request
|
||||
|
||||
**Validation:**
|
||||
- Send to debug endpoint
|
||||
- Empty response = valid
|
||||
- Check validationMessages array
|
||||
Reference in New Issue
Block a user