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
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:

VITE_GA_MEASUREMENT_ID=G-XXXXXXXXXX

Replace G-XXXXXXXXXX with your actual Measurement ID.

3. Restart the Application

For the changes to take effect:

# 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:

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:

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

Check cookie consent

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
• GDPR Compliance