Google Analytics 4 (GA4) API — SKILL.md

---
name: "Google Analytics 4 (GA4) API"
description: "Implement GA4: gtag.js setup, event tracking (auto/recommended/custom), e-commerce events, Measurement Protocol (server-side), Data API (reporting), BigQuery export, consent mode v2, attribution, and alternatives (Mixpanel, PostHog, Plausible)."
version: "1.0.0"
author: "skynet"
category: "dev"
agents: ["claude-code", "codex", "gemini"]
tags: ["google-analytics", "ga4", "analytics", "tracking", "api", "saas"]
---

# Google Analytics 4 (GA4) API

---
name: "Google Analytics 4 (GA4) API"
description: "Implement GA4: gtag.js setup, event tracking (auto/recommended/custom), e-commerce events, Measurement Protocol (server-side), Data API (reporting), BigQuery export, consent mode v2, attribution, and "
version: "1.0.0"
author: "skynet"
category: "dev"
tags: ["google-analytics", "ga4", "analytics", "tracking", "api", "saas"]
---

I will start by checking the knowledge graph for any existing GA4 integration patterns or notes to ensure consistency with your existing documentation, then I will synthesize the comprehensive technical reference.
# Google Analytics 4 (GA4) Technical Reference for SaaS

This reference provides a technical foundation for integrating GA4 into SaaS applications, moving beyond basic page views to deep product analytics.

## 1. SETUP: Foundations of GA4

SaaS applications require a unified view across web and mobile platforms.

*   **Property Creation:** Create one GA4 property for the entire application.
*   **Data Streams:** 
    *   **Web:** For your marketing site and web app.
    *   **iOS/Android:** For native mobile apps (connected via Firebase).
*   **Measurement ID:** Format `G-XXXXXXXXXX`. This is the public ID for `gtag.js`.
*   **Google Tag Manager (GTM) vs. gtag.js:**
    *   **GTM:** Recommended for most SaaS. It allows marketing teams to add tags (e.g., LinkedIn, Meta) without code changes.
    *   **gtag.js:** Best for developers who want direct control and minimal overhead.

**gtag.js Installation Code:**
```html
<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'G-XXXXXXXXXX', {
    'user_id': 'USER_123', // Critical for cross-device SaaS tracking
    'debug_mode': true     // See events in Realtime > DebugView
  });
</script>
```

---

## 2. EVENT TRACKING: Beyond Page Views

GA4 is an event-based model. Everything is an event.

*   **Auto-collected Events:** `first_visit`, `session_start`, `user_engagement`.
*   **Enhanced Measurement:** Automatically tracks `scrolls`, `outbound clicks`, `site search`, `video engagement`, and `file downloads`.
*   **Recommended Events for SaaS:**
    *   `sign_up`: Use when a user creates a new account.
    *   `login`: Track when a user authenticates.
    *   `share`: When a user invites a teammate or shares a resource.
*   **Custom Events:** For specific SaaS actions like `project_created`, `report_exported`, `api_key_generated`.
*   **User Properties:** Persistent attributes like `plan_type` (Free, Pro, Enterprise), `industry`, or `signup_date`.

---

## 3. E-COMMERCE: Subscription & Transaction Tracking

SaaS revenue tracking uses GA4’s E-commerce schema.

*   **Key Events:**
    *   `view_item`: User views a pricing plan.
    *   `add_to_cart`: User selects a plan but hasn't paid.
    *   `begin_checkout`: User enters billing info.
    *   `purchase`: User successfully subscribes.
*   **Item Parameters:** Use `item_id` for the plan SKU and `item_category` for the billing frequency (e.g., `monthly`, `annual`).

**Implementation Example:**
```javascript
gtag("event", "purchase", {
    transaction_id: "T_12345",
    value: 49.00,
    currency: "USD",
    items: [
        {
          item_id: "pro_plan_monthly",
          item_name: "Pro Plan",
          price: 49.00,
          quantity: 1
        }
    ]
});
```

---

## 4. MEASUREMENT PROTOCOL: Server-Side Tracking

Used for events that happen outside the browser (e.g., Stripe webhooks, offline conversions, backend jobs).

*   **API Secret:** Generate in GA4 Admin > Data Streams > [Stream] > Measurement Protocol API secrets.
*   **Endpoint:** `https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_SECRET`
*   **Constraint:** You MUST provide a `client_id` (cookie-based) or `app_instance_id` to link backend events to a web/app session.

**Python Implementation:**
```python
import requests
import json

url = "https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_SECRET"
payload = {
    "client_id": "123456.7891011", # Retrieve from _ga cookie or pass from frontend
    "events": [{
        "name": "subscription_renewed",
        "params": {
            "value": 99.00,
            "currency": "USD"
        }
    }]
}
requests.post(url, data=json.dumps(payload))
```

---

## 5. DATA API (Reporting)

The [Google Analytics Data API (v1)](https://developers.google.com/analytics/devguides/reporting/data/v1) allows programmatic access to GA4 report data.

*   **runReport:** The primary method for building custom dashboards.
*   **Dimensions:** `eventName`, `pagePath`, `country`, `deviceCategory`.
*   **Metrics:** `activeUsers`, `sessions`, `conversions`, `totalRevenue`.
*   **Quota Limits:** Be aware of the "Standard" vs. "360" limits. Cache your API responses.

---

## 6. ADMIN API

Used to manage GA4 accounts and properties programmatically. Use this if you are building a platform that creates a unique GA4 property for each of your customers (e.g., a white-label SaaS).

*   **Capabilities:** Create properties, data streams, custom dimensions/metrics, and manage user permissions.

---

## 7. BIGQUERY EXPORT: Raw Data Access

GA4 offers a free daily export to BigQuery (within sandbox limits).

*   **Schema:** Raw event data in a nested/repeated BigQuery format.
*   **Why use it?** 
    *   Calculate LTV across multiple years.
    *   Join GA4 data with internal database tables (PostgreSQL/BigQuery).
    *   Bypass GA4 UI data thresholds and sampling.
*   **Cost:** Storage and query costs in BigQuery, but the export itself is free.

---

## 8. CONSENT MODE V2

Mandatory for EU/EEA traffic to maintain attribution and remarketing capabilities.

*   **ad_storage:** For advertising cookies.
*   **analytics_storage:** For analytics cookies.
*   **ad_user_data:** For sending user data to Google for advertising.
*   **ad_personalization:** For remarketing.
*   **Advanced vs Basic:** 
    *   *Advanced:* Sends "pings" to GA4 even when consent is denied (used for behavioral modeling).
    *   *Basic:* No data is sent until the user grants consent.

---

## 9. ATTRIBUTION

GA4 defaults to **Data-Driven Attribution (DDA)**.

*   **DDA:** Uses machine learning to evaluate all touchpoints (Search, Direct, Social) and assign credit based on their actual impact on conversion.
*   **Conversion Paths:** View how users traverse multiple channels before signing up in the "Advertising" section.

---

## 10. ALTERNATIVES

When GA4 might not be the best fit:

| Tool | Best For | Why? |
| :--- | :--- | :--- |
| **Mixpanel / Amplitude** | Product Analytics | Superior retention/cohort analysis and user pathing. |
| **PostHog** | Engineers / Open Source | Session recording, feature flags, and heatmaps in one tool. |
| **Plausible / Fathom** | Privacy-First | Cookie-less, lightweight, and 100% GDPR compliant out-of-the-box. |

---

## 11. GOTCHAS: Common Pitfalls

1.  **Data Thresholds (Sampling):** GA4 applies "thresholding" (hiding rows with small user counts) if Google Signals is enabled to prevent de-anonymizing users.
2.  **Latency:** It takes 24-48 hours for data to fully process in standard reports. Use the "Realtime" report for immediate feedback.
3.  **Data Retention:** Default is **2 months**. Manually change this to **14 months** in Admin > Data Settings > Data Retention to avoid losing year-over-year comparison data in Explorations.
4.  **Session Definition:** GA4 sessions don't restart at midnight or on a change in campaign source (unlike UA).
5.  **Cardinality:** High-cardinality dimensions (e.g., unique `order_id` as a dimension) will cause rows to be grouped under `(other)`. Use BigQuery for high-cardinality analysis.