[codex] Add competition analytics tracking

.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.test.tsx

@@ -0,0 +1,78 @@
+import { renderHook } from '@testing-library/react';
+import { PropsWithChildren } from 'react';
+import { MemoryRouter } from 'react-router-dom';
+import { trackCompetitionEvent } from '@/lib/analytics';
+import { useAuth } from '@/providers/AuthProvider';
+import { useCompetitionAnalytics } from './useCompetitionAnalytics';
+
+jest.mock('@/lib/analytics', () => ({
+  trackCompetitionEvent: jest.fn(),
+}));
+
+jest.mock('@/providers/AuthProvider', () => ({
+  useAuth: jest.fn(),
+}));
+
+jest.mock('../usePageActivityTracking', () => ({
+  usePageActivityTracking: jest.fn(),
+}));
+
+const wrapper = (initialEntry: string) => {
+  function TestWrapper({ children }: PropsWithChildren) {
+    return <MemoryRouter initialEntries={[initialEntry]}>{children}</MemoryRouter>;
+  }
+
+  return TestWrapper;
+};
+
+describe('useCompetitionAnalytics', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.mocked(useAuth).mockReturnValue({
+      user: null,
+    } as unknown as ReturnType<typeof useAuth>);
+  });
+
+  it('tracks competition views with stable labels for every competition route', () => {
+    renderHook(() => useCompetitionAnalytics('ExampleComp2026'), {
+      wrapper: wrapper('/competitions/ExampleComp2026/events/333-r1/2'),
+    });
+
+    expect(trackCompetitionEvent).toHaveBeenCalledWith('competition_viewed', {
+      competition_id: 'ExampleComp2026',
+      page: 'event_group',
+      user_id: undefined,
+    });
+  });
+
+  it('keeps feature-specific events for known competition pages', () => {
+    renderHook(() => useCompetitionAnalytics('ExampleComp2026'), {
+      wrapper: wrapper('/competitions/ExampleComp2026/admin/remote'),
+    });
+
+    expect(trackCompetitionEvent).toHaveBeenCalledWith('live_activities_opened', {
+      competition_id: 'ExampleComp2026',
+      page: 'live_activities',
+      feature: 'live_activities',
+      user_id: undefined,
+    });
+  });
+
+  it.each([
+    ['/competitions/ExampleComp2026/activities', 'schedule'],
+    ['/competitions/ExampleComp2026/activities/1', 'schedule_activity'],
+    ['/competitions/ExampleComp2026/rooms', 'schedule_rooms'],
+    ['/competitions/ExampleComp2026/rooms/main', 'schedule_room'],
+  ])('tracks schedule views for %s', (initialEntry, page) => {
+    renderHook(() => useCompetitionAnalytics('ExampleComp2026'), {
+      wrapper: wrapper(initialEntry),
+    });
+
+    expect(trackCompetitionEvent).toHaveBeenCalledWith('schedule_viewed', {
+      competition_id: 'ExampleComp2026',
+      page,
+      feature: undefined,
+      user_id: undefined,
+    });
+  });
+});

src/hooks/useCompetitionAnalytics/useCompetitionAnalytics.ts

@@ -0,0 +1,88 @@
+import { useEffect, useMemo, useRef } from 'react';
+import { useLocation } from 'react-router-dom';
+import { trackCompetitionEvent } from '@/lib/analytics';
+import { competitionPageName } from '@/lib/analyticsPages';
+import { useAuth } from '@/providers/AuthProvider';
+import { usePageActivityTracking } from '../usePageActivityTracking';
+
+const featureViewEventName = (page: string) => {
+  if (page === 'groups') {
+    return 'groups_viewed';
+  }
+
+  if (
+    page === 'schedule' ||
+    page === 'schedule_activity' ||
+    page === 'schedule_rooms' ||
+    page === 'schedule_room'
+  ) {
+    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 = featureViewEventName(page);
+    if (!eventName) {
+      return;
+    }
+
+    const eventKey = `${competitionId}:${location.pathname}${location.search}:${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, location.search, 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,33 @@
 import { useEffect } from 'react';
 import ReactGA from 'react-ga4';
 import { useLocation } from 'react-router-dom';
+import { configureUmamiAnalytics, 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();
+  const umamiSrc = import.meta.env.VITE_UMAMI_SRC;
+  const umamiWebsiteId = import.meta.env.VITE_UMAMI_WEBSITE_ID;
+
+  configureUmamiAnalytics({
+    src: umamiSrc,
+    websiteId: umamiWebsiteId,
+  });
 
   useEffect(() => {
-    if (ReactGA.isInitialized) {
+    loadUmamiScript({
+      src: umamiSrc,
+      websiteId: umamiWebsiteId,
+    });
+  }, [umamiSrc, umamiWebsiteId]);
+
+  useEffect(() => {
+    identifyUser(user?.id);
+  }, [user?.id]);
+
+  useEffect(() => {
+    if (!trackingCode || ReactGA.isInitialized) {
       return;
     }
 
@@ -39,10 +58,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 +70,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,