a786b1d92d
Prepared the application for Google Analytics 4 tracking with full GDPR/RODO compliance. GA only loads after user explicitly accepts cookies. Features: - Automatic page view tracking on route changes - Custom event tracking for key user actions - Privacy-first: GA loads only after cookie consent - Easy configuration via environment variable - Comprehensive tracking utilities for common events Implementation: - Created analytics.js with GA initialization and event tracking functions - Created usePageTracking hook for automatic page view tracking - Integrated GA into App.jsx with AnalyticsWrapper component - Updated CookieConsent to initialize GA after user consent - Added VITE_GA_MEASUREMENT_ID to .env.example Custom events tracked: - login, sign_up (authentication) - match_request, match_accepted (matching) - webrtc_connection, file_transfer (WebRTC) - event_join, recording_suggestion (events/recording) - search (search functionality) Setup: 1. Add VITE_GA_MEASUREMENT_ID=G-XXXXXXXXXX to .env 2. Restart frontend container 3. GA will auto-load after user accepts cookies Documentation: - Created comprehensive setup guide in docs/GOOGLE_ANALYTICS_SETUP.md - Includes troubleshooting, debugging tips, and usage examples
144 lines
3.7 KiB
Markdown
144 lines
3.7 KiB
Markdown
# 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)
|