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.