@friedbotstudio/create-baseline 0.2.0 → 0.3.0

package/obj/template/.claude/skills/google-analytics/references/measurement-protocol.md

@@ -0,0 +1,519 @@
+# 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
+
+| Use Case | Description |
+|----------|-------------|
+| Server-side tracking | Events from backend systems |
+| Offline conversions | Import CRM/POS data |
+| Payment processing | Track post-checkout events |
+| Subscription renewals | Server-initiated events |
+| Lead enrichment | Enhance leads from backend |
+| IoT devices | Non-browser environments |
+| Headless architectures | API-first systems |
+
+## 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)
+
+```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
+
+| Field | Type | Description |
+|-------|------|-------------|
+| client_id | string | Unique client identifier (UUID recommended) |
+| events | array | Array of event objects (max 25) |
+| events[].name | string | Event name (max 40 chars) |
+
+### Optional Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| user_id | string | User ID for cross-device |
+| timestamp_micros | integer | Event timestamp (microseconds) |
+| user_properties | object | User-level properties |
+| consent | object | Consent status |
+| non_personalized_ads | boolean | Disable ad personalisation |
+
+## Common Event Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| session_id | string | Session identifier |
+| engagement_time_msec | integer | Engagement time (ms) |
+| page_location | string | Full URL |
+| page_title | string | Page title |
+| value | number | Monetary value |
+| currency | string | ISO 4217 code |
+| transaction_id | string | Unique transaction ID |
+| items | array | E-commerce items |
+
+## Implementation Examples
+
+### 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(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:**
+
+```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(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
+<?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
+
+```bash
+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
+
+```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
+- Production returns 204 (no content)
+
+## Validation Codes
+
+| Code | Description | Fix |
+|------|-------------|-----|
+| NAME_INVALID | Invalid event/parameter name | snake_case, max 40 chars |
+| NAME_RESERVED | Reserved name used | Check reserved names |
+| VALUE_INVALID | Invalid parameter value | Check data type |
+| 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 per request |
+
+## Best Practices
+
+### 1. Always Validate First
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+payload = {
+    "client_id": "client_123",
+    "consent": {
+        "ad_storage": "denied",
+        "analytics_storage": "granted"
+    },
+    "events": [...]
+}
+```
+
+## Limits
+
+| Limit | Value |
+|-------|-------|
+| Events per request | 25 |
+| Event name length | 40 characters |
+| Parameter name length | 40 characters |
+| Parameter value length | 100 characters |
+| Parameters per event | 25 |
+| User properties per request | 25 |
+| Timestamp range | 3 days past, 72 hours future |
+
+## 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