spotlightcam/docs/GOOGLE_ANALYTICS_SETUP.md

# Google Analytics Setup Guide

This document explains how to configure Google Analytics 4 (GA4) for spotlight.cam.

## Prerequisites

1. Google Analytics account
2. GA4 property created for spotlight.cam

## Setup Instructions

### 1. Get your Measurement ID

1. Go to [Google Analytics](https://analytics.google.com/)
2. Select your property
3. Go to **Admin** (bottom left)
4. Under **Property**, click **Data Streams**
5. Select your web stream (or create one)
6. Copy the **Measurement ID** (format: `G-XXXXXXXXXX`)

### 2. Configure Environment Variable

Add your Measurement ID to the `.env` file in the project root:

```bash
VITE_GA_MEASUREMENT_ID=G-XXXXXXXXXX
```

Replace `G-XXXXXXXXXX` with your actual Measurement ID.

### 3. Restart the Application

For the changes to take effect:

```bash
# Rebuild and restart the frontend container
docker compose up -d --build frontend
```

## How It Works

### Automatic Tracking

The application automatically tracks:

- **Page views**: Every route change is tracked
- **User consent**: GA only loads if user accepts cookies
- **Custom events**: See below for list of tracked events

### Privacy & GDPR Compliance

- GA script loads **only after** user accepts cookies
- If user declines cookies, no tracking occurs
- Consent is stored in `localStorage`

### Custom Events

The following custom events are tracked:

| Event | Description | Parameters |
|-------|-------------|------------|
| `login` | User logs in | `method` |
| `sign_up` | User registers | `method` |
| `match_request` | User sends match request | `event_slug` |
| `match_accepted` | User accepts match | `match_slug` |
| `webrtc_connection` | WebRTC connection status | `status` |
| `file_transfer` | File transfer via WebRTC | `file_size`, `success` |
| `event_join` | User joins event | `event_slug` |
| `recording_suggestion` | Recording suggestion action | `action` |
| `search` | User searches | `search_term` |

### Using Analytics in Code

Import and use the tracking functions:

```javascript
import { trackEvent, trackLogin, trackMatchRequest } from './utils/analytics';

// Track custom event
trackEvent('button_click', { button_name: 'register' });

// Track login
trackLogin('email');

// Track match request
trackMatchRequest('event-slug-123');
```

## Debugging

### Check if GA is loaded

Open browser console and run:

```javascript
console.log(window.gtag);  // Should be a function
console.log(window.dataLayer);  // Should be an array
```

### Check cookie consent

```javascript
console.log(localStorage.getItem('cookieConsent'));  // 'accepted' or 'declined'
```

### View GA events in real-time

1. Go to Google Analytics
2. Navigate to **Reports** → **Realtime**
3. You should see your page views and events as they happen

## Troubleshooting

### GA not loading

1. Check that `VITE_GA_MEASUREMENT_ID` is set in `.env`
2. Verify user accepted cookies (check browser localStorage)
3. Check browser console for errors
4. Ensure frontend container was rebuilt after adding env variable

### Events not showing up

1. Wait 24-48 hours for events to appear in standard reports
2. Use **Realtime** view for immediate feedback
3. Check that events are being sent: `console.log(window.dataLayer)`

### Ad blockers

Note: Users with ad blockers may block Google Analytics. This is expected behavior.

## Production Deployment

When deploying to production:

1. Set `VITE_GA_MEASUREMENT_ID` in production environment
2. Verify tracking works in production domain
3. Update GA4 property settings if domain changes
4. Configure data retention and user deletion settings in GA

## References

- [GA4 Documentation](https://developers.google.com/analytics/devguides/collection/ga4)
- [GDPR Compliance](https://support.google.com/analytics/answer/9019185)