Google Analytics Integration

��� Overview

Google Analytics integration providing access to web analytics data through both Universal Analytics (v3) and Google Analytics 4 (v4) APIs. Supports account management, property listing, and comprehensive reporting capabilities with automatic OAuth token management.

Provider: Google (https://analytics.google.com)
API Versions: v3 (Universal Analytics), v4 (Google Analytics 4)
Integration Type: OAuth 2.0 with automatic token refresh

��� Documentation Structure

This integration is organized into the following sections:

1. Authentication - OAuth 2.0 flow, token management, and connection handling
2. Accounts & Properties - List accounts, properties, and views for both v3 and v4
3. Report Generation - Create custom analytics reports with dimensions and metrics

��� Features

• ✅ Dual Version Support: Works with both v3 (Universal Analytics) and v4 (GA4)
• ✅ OAuth 2.0: Secure authentication with automatic token refresh
• ✅ Account Management: List accounts, properties, and views
• ✅ Custom Reports: Generate reports with custom dimensions and metrics
• ✅ Token Management: Automatic refresh and invalidation handling
• ✅ Sub-account Support: Works with DashClicks sub-accounts
• ✅ Notifications: FCM and email notifications for connection events

��� Architecture

Frontend Request
       ↓
  OAuth Flow
       ↓
Token Storage (MongoDB)
       ↓
  Auto Refresh
       ↓
Google Analytics API (v3 or v4)
       ↓
Report Data / Account Lists

���️ MongoDB Collections

��� Detailed Schema: See Database Collections Documentation

google.analytics.tokens

Purpose: Store OAuth 2.0 tokens for Google Analytics access

Key Fields:

• email (String) - User's Google email address
• access_token (String, encrypted) - OAuth access token
• refresh_token (String, encrypted) - OAuth refresh token
• token_expires_at (Date) - Token expiration timestamp
• accountID (ObjectId) - DashClicks account reference
• userID (ObjectId) - DashClicks user reference
• scope (String) - OAuth scopes granted

Indexes:

• { accountID: 1, userID: 1 } (unique) - Primary lookup
• { userID: 1 } - User-based queries
• { accountID: 1 } - Account-based queries

analytics_googleanalytics_userconfigs

Purpose: Store user-specific Google Analytics configuration

Key Fields:

• accountId (String) - GA account ID
• propertyId (String) - GA property ID
• viewId (String) - GA view ID (v3 only)
• timezone (String) - User timezone
• currency (String) - Currency for reports
• version (String) - "v3" or "v4"
• accountID (ObjectId) - DashClicks account reference
• userID (ObjectId) - DashClicks user reference

Indexes:

• { accountID: 1, userID: 1 } (unique) - Primary lookup

��� Directory Structure

Source Code Location:

external/Integrations/GoogleAnalytics/
├── Controllers/
│   ├── auth.js           # OAuth authentication handlers
│   └── analytics.js      # Analytics report controllers
├── Models/
│   └── keys.js          # Token model methods
├── Routes/
│   ├── auth.js          # Auth endpoints
│   └── analytics.js     # Analytics endpoints
├── validators/
│   └── index.js         # Request validation schemas
├── providers/
│   └── google-analytics.js  # Google API wrapper
└── index.js             # Route registration

Shared Models Used:

• shared/models/google-analytics-token.js
• shared/models/analytics-googleanalytics-userconfig.js
• shared/models/account.js
• shared/models/user.js

�� Quick Start

1. Configure Environment Variables

GOOGLE_ANALYTICS_CLIENT_ID=your_client_id
GOOGLE_ANALYTICS_CLIENT_SECRET=your_client_secret
GOOGLE_ANALYTICS_CALLBACK_URL=https://api.dashclicks.com/v1/integrations/google/analytics/auth/callback

2. Initiate OAuth Flow

GET /v1/integrations/google/analytics/auth/login?forward_url=https://app.dashclicks.com/integrations
Authorization: Bearer {jwt_token}

3. List Accounts

GET /v1/integrations/google/analytics/accounts?version=v4
Authorization: Bearer {jwt_token}

4. Generate Report

GET /v1/integrations/google/analytics/report/{viewId}?start=2025-09-01&end=2025-10-10&metrics=users,sessions&dimensions=country
Authorization: Bearer {jwt_token}

��� API Endpoints Summary

Method	Endpoint	Description
GET	/auth/login	Initiate OAuth 2.0 flow
GET	/auth/callback	Handle OAuth callback
POST	/useranalyticsconfig	Save user configuration
DELETE	/auth	Disconnect integration
GET	/accounts	List accounts/properties/views
GET	/:accountid/properties	List properties
GET	/:accountid/properties/:propertyid/views	List views (v3)
GET	/report/:id	Generate analytics report

��� Related Documentation

• Google Analytics Reporting API v3
• Google Analytics Data API v4
• OAuth 2.0 Configuration

��� Version Differences

v3 (Universal Analytics - Legacy)

• Structure: Account → Property → View
• View ID Required: For reporting
• Pagination: Page-based
• Status: Being phased out by Google

v4 (Google Analytics 4 - Current)

• Structure: Account → Property (no views)
• Property ID Used: For reporting
• Pagination: Token-based
• Features: Event-based analytics, cross-platform tracking