Add competition analytics tracking

Load configured Umami analytics, attach competition page events, and track active page time.

Include environment declarations and focused coverage for analytics helpers and activity timers.

Author: coder13

.env.example

@@ -0,0 +1,4 @@
+VITE_APP_ENV=
+VITE_GA_MEASUREMENT_ID=
+VITE_UMAMI_SRC=
+VITE_UMAMI_WEBSITE_ID=

src/hooks/useCompetitionAnalytics/index.ts

@@ -0,0 +1 @@
+export * from './useCompetitionAnalytics';

src/hooks/useCompetitionAnalytics/useCompetitionAnalytics.ts

@@ -0,0 +1,105 @@
+import { useEffect, useMemo, useRef } from 'react';
+import { useLocation } from 'react-router-dom';
+import { trackCompetitionEvent } from '@/lib/analytics';
+import { useAuth } from '@/providers/AuthProvider';
+import { usePageActivityTracking } from '../usePageActivityTracking';
+
+const competitionPageName = (pathname: string, competitionId: string) => {
+  const competitionRoot = `/competitions/${competitionId}`;
+  const relativePath = pathname.replace(competitionRoot, '') || '/';
+
+  if (relativePath === '/') {
+    return 'groups';
+  }
+
+  if (relativePath.startsWith('/activities') || relativePath.startsWith('/rooms')) {
+    return 'schedule';
+  }
+
+  if (relativePath === '/live' || relativePath === '/admin/remote') {
+    return 'live_activities';
+  }
+
+  if (relativePath === '/admin/scramblers') {
+    return 'assignments';
+  }
+
+  return relativePath.replace(/^\//, '').replace(/\//g, '_') || 'competition';
+};
+
+const pageViewEventName = (page: string) => {
+  if (page === 'groups') {
+    return 'groups_viewed';
+  }
+
+  if (page === 'schedule') {
+    return 'schedule_viewed';
+  }
+
+  if (page === 'assignments') {
+    return 'assignments_viewed';
+  }
+
+  if (page === 'live_activities') {
+    return 'live_activities_opened';
+  }
+
+  return undefined;
+};
+
+export const useCompetitionAnalytics = (competitionId?: string) => {
+  const location = useLocation();
+  const { user } = useAuth();
+  const lastCompetitionId = useRef<string>();
+  const lastPageEventKey = useRef<string>();
+
+  const page = useMemo(
+    () => (competitionId ? competitionPageName(location.pathname, competitionId) : 'competition'),
+    [competitionId, location.pathname],
+  );
+
+  useEffect(() => {
+    if (!competitionId) {
+      return;
+    }
+
+    if (lastCompetitionId.current !== competitionId) {
+      trackCompetitionEvent('competition_viewed', {
+        competition_id: competitionId,
+        page,
+        user_id: user?.id,
+      });
+      lastCompetitionId.current = competitionId;
+    }
+  }, [competitionId, page, user?.id]);
+
+  useEffect(() => {
+    if (!competitionId) {
+      return;
+    }
+
+    const eventName = pageViewEventName(page);
+    if (!eventName) {
+      return;
+    }
+
+    const eventKey = `${competitionId}:${location.pathname}:${eventName}`;
+    if (lastPageEventKey.current === eventKey) {
+      return;
+    }
+
+    trackCompetitionEvent(eventName, {
+      competition_id: competitionId,
+      page,
+      feature: page === 'live_activities' ? 'live_activities' : undefined,
+      user_id: user?.id,
+    });
+    lastPageEventKey.current = eventKey;
+  }, [competitionId, location.pathname, page, user?.id]);
+
+  usePageActivityTracking({
+    competitionId,
+    page,
+    userId: user?.id,
+  });
+};

src/hooks/usePageActivityTracking/index.ts

@@ -0,0 +1 @@
+export * from './usePageActivityTracking';

src/hooks/usePageActivityTracking/usePageActivityTracking.test.ts

@@ -0,0 +1,75 @@
+import { renderHook } from '@testing-library/react';
+import { trackCompetitionEvent } from '@/lib/analytics';
+import { usePageActivityTracking } from './usePageActivityTracking';
+
+jest.mock('@/lib/analytics', () => ({
+  trackCompetitionEvent: jest.fn(),
+}));
+
+const setVisibilityState = (visibilityState: DocumentVisibilityState) => {
+  Object.defineProperty(document, 'visibilityState', {
+    configurable: true,
+    value: visibilityState,
+  });
+};
+
+describe('usePageActivityTracking', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    setVisibilityState('visible');
+    jest.mocked(trackCompetitionEvent).mockClear();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it('tracks active visible time every 60 seconds', () => {
+    renderHook(() =>
+      usePageActivityTracking({
+        competitionId: 'ExampleComp2026',
+        page: 'groups',
+        userId: 123,
+      }),
+    );
+
+    jest.advanceTimersByTime(59_000);
+    expect(trackCompetitionEvent).not.toHaveBeenCalled();
+
+    jest.advanceTimersByTime(1_000);
+    expect(trackCompetitionEvent).toHaveBeenCalledWith('page_active_60s', {
+      competition_id: 'ExampleComp2026',
+      page: 'groups',
+      user_id: 123,
+    });
+  });
+
+  it('does not track while hidden', () => {
+    setVisibilityState('hidden');
+
+    renderHook(() =>
+      usePageActivityTracking({
+        competitionId: 'ExampleComp2026',
+        page: 'groups',
+      }),
+    );
+
+    jest.advanceTimersByTime(60_000);
+
+    expect(trackCompetitionEvent).not.toHaveBeenCalled();
+  });
+
+  it('clears the timer on unmount', () => {
+    const { unmount } = renderHook(() =>
+      usePageActivityTracking({
+        competitionId: 'ExampleComp2026',
+        page: 'groups',
+      }),
+    );
+
+    unmount();
+    jest.advanceTimersByTime(60_000);
+
+    expect(trackCompetitionEvent).not.toHaveBeenCalled();
+  });
+});

src/hooks/usePageActivityTracking/usePageActivityTracking.ts

@@ -0,0 +1,40 @@
+import { useEffect } from 'react';
+import { trackCompetitionEvent } from '@/lib/analytics';
+
+const ACTIVE_INTERVAL_MS = 60_000;
+
+interface UsePageActivityTrackingParams {
+  competitionId?: string;
+  page: string;
+  userId?: number;
+}
+
+export const usePageActivityTracking = ({
+  competitionId,
+  page,
+  userId,
+}: UsePageActivityTrackingParams) => {
+  useEffect(() => {
+    if (!competitionId || typeof document === 'undefined') {
+      return undefined;
+    }
+
+    const trackActivePage = () => {
+      if (document.visibilityState !== 'visible') {
+        return;
+      }
+
+      trackCompetitionEvent('page_active_60s', {
+        competition_id: competitionId,
+        page,
+        user_id: userId,
+      });
+    };
+
+    const intervalId = window.setInterval(trackActivePage, ACTIVE_INTERVAL_MS);
+
+    return () => {
+      window.clearInterval(intervalId);
+    };
+  }, [competitionId, page, userId]);
+};

src/hooks/usePageTracking/usePageTracking.ts

@@ -1,14 +1,26 @@
 import { useEffect } from 'react';
 import ReactGA from 'react-ga4';
 import { useLocation } from 'react-router-dom';
+import { identifyUser, loadUmamiScript } from '@/lib/analytics';
 import { useAuth } from '@/providers/AuthProvider';
 
-export const usePageTracking = (trackingCode) => {
+export const usePageTracking = (trackingCode?: string) => {
   const location = useLocation();
   const { user } = useAuth();
 
   useEffect(() => {
-    if (ReactGA.isInitialized) {
+    loadUmamiScript({
+      src: import.meta.env.VITE_UMAMI_SRC,
+      websiteId: import.meta.env.VITE_UMAMI_WEBSITE_ID,
+    });
+  }, []);
+
+  useEffect(() => {
+    identifyUser(user?.id);
+  }, [user?.id]);
+
+  useEffect(() => {
+    if (!trackingCode || ReactGA.isInitialized) {
       return;
     }
 
@@ -39,10 +51,10 @@ export const usePageTracking = (trackingCode) => {
           delegate_status: null,
         });
       }
-    } else if (!ReactGA.isInitialized) {
+    } else if (trackingCode && !ReactGA.isInitialized) {
       console.log('Would have set userId to', user?.id);
     }
-  }, [user]);
+  }, [trackingCode, user]);
 
   useEffect(() => {
     if (ReactGA.isInitialized) {
@@ -51,8 +63,8 @@ export const usePageTracking = (trackingCode) => {
         page: location.pathname + location.search,
         title: document.title,
       });
-    } else {
+    } else if (trackingCode) {
       console.log('Would have logged pageview for', location);
     }
-  }, [location]);
+  }, [location, trackingCode]);
 };

src/layouts/CompetitionLayout/CompetitionLayout.tsx

@@ -7,6 +7,7 @@ import { ErrorFallback, LastFetchedAt, NoteBox, NotifyCompRemoteBar } from '@/co
 import { Container } from '@/components/Container';
 import { StyledNavLink } from '@/components/StyledNavLink/StyledNavLink';
 import { useWcif } from '@/hooks/queries/useWcif';
+import { useCompetitionAnalytics } from '@/hooks/useCompetitionAnalytics';
 import { useApp } from '@/providers/AppProvider';
 import { WCIFProvider } from '@/providers/WCIFProvider';
 import { useCompetitionLayoutTabs } from './CompetitionLayout.tabs';
@@ -20,6 +21,8 @@ export function CompetitionLayout() {
 
   const { data: wcif, dataUpdatedAt, isFetching } = useWcif(competitionId!);
 
+  useCompetitionAnalytics(competitionId);
+
   const { tabs } = useCompetitionLayoutTabs({
     competitionId: competitionId!,
     wcif: wcif,

src/lib/analytics.test.ts

@@ -0,0 +1,88 @@
+import {
+  identifyUser,
+  isValidEventName,
+  loadUmamiScript,
+  trackCompetitionEvent,
+  trackEvent,
+} from './analytics';
+
+describe('analytics', () => {
+  beforeEach(() => {
+    document.head.innerHTML = '';
+    window.umami = undefined;
+  });
+
+  it('loads the Umami script only when configured', () => {
+    loadUmamiScript();
+
+    expect(document.querySelector('script')).toBeNull();
+
+    loadUmamiScript({
+      src: 'https://analytics.example.com/script.js',
+      websiteId: 'website-id',
+    });
+    loadUmamiScript({
+      src: 'https://analytics.example.com/script.js',
+      websiteId: 'website-id',
+    });
+
+    const scripts = document.querySelectorAll('script');
+    expect(scripts).toHaveLength(1);
+    expect(scripts[0]).toHaveAttribute('src', 'https://analytics.example.com/script.js');
+    expect(scripts[0]).toHaveAttribute('data-website-id', 'website-id');
+  });
+
+  it('no-ops when Umami is not available', () => {
+    expect(() => trackEvent('competition_viewed')).not.toThrow();
+  });
+
+  it('tracks event data with shared app and auth properties', () => {
+    const track = jest.fn();
+    window.umami = { track };
+
+    trackCompetitionEvent('competition_viewed', {
+      competitionId: 'ExampleComp2026',
+      page: 'groups',
+      user_id: 123,
+    });
+
+    expect(track).toHaveBeenCalledWith(
+      'competition_viewed',
+      expect.objectContaining({
+        app: 'competitiongroups',
+        auth_status: 'logged_in',
+        competition_id: 'ExampleComp2026',
+        page: 'groups',
+        user_id: '123',
+      }),
+    );
+  });
+
+  it('does not send invalid event names', () => {
+    const track = jest.fn();
+    window.umami = { track };
+
+    expect(isValidEventName('x'.repeat(51))).toBe(false);
+    trackEvent('x'.repeat(51));
+
+    expect(track).not.toHaveBeenCalled();
+  });
+
+  it('identifies logged-in users by numeric ID only', () => {
+    const identify = jest.fn();
+    window.umami = {
+      identify,
+      track: jest.fn(),
+    };
+
+    identifyUser(123);
+
+    expect(identify).toHaveBeenCalledWith(
+      '123',
+      expect.objectContaining({
+        app: 'competitiongroups',
+        auth_status: 'logged_in',
+      }),
+    );
+  });
+});