Fix queued Umami competition events

Author: coder13

src/hooks/usePageTracking/usePageTracking.ts

@@ -1,19 +1,26 @@
 import { useEffect } from 'react';
 import ReactGA from 'react-ga4';
 import { useLocation } from 'react-router-dom';
-import { identifyUser, loadUmamiScript } from '@/lib/analytics';
+import { configureUmamiAnalytics, identifyUser, loadUmamiScript } from '@/lib/analytics';
 import { useAuth } from '@/providers/AuthProvider';
 
 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(() => {
     loadUmamiScript({
-      src: import.meta.env.VITE_UMAMI_SRC,
-      websiteId: import.meta.env.VITE_UMAMI_WEBSITE_ID,
+      src: umamiSrc,
+      websiteId: umamiWebsiteId,
     });
-  }, []);
+  }, [umamiSrc, umamiWebsiteId]);
 
   useEffect(() => {
     identifyUser(user?.id);

src/lib/analytics.test.ts

@@ -1,4 +1,6 @@
 import {
+  __resetAnalyticsForTests,
+  configureUmamiAnalytics,
   identifyUser,
   isValidEventName,
   loadUmamiScript,
@@ -8,6 +10,7 @@ import {
 
 describe('analytics', () => {
   beforeEach(() => {
+    __resetAnalyticsForTests();
     document.head.innerHTML = '';
     window.umami = undefined;
   });
@@ -36,6 +39,37 @@ describe('analytics', () => {
     expect(() => trackEvent('competition_viewed')).not.toThrow();
   });
 
+  it('flushes route events that fire before the Umami script loads', () => {
+    configureUmamiAnalytics({
+      src: 'https://analytics.example.com/script.js',
+      websiteId: 'website-id',
+    });
+
+    trackCompetitionEvent('competition_viewed', {
+      competitionId: 'ExampleComp2026',
+      page: 'groups',
+    });
+
+    loadUmamiScript({
+      src: 'https://analytics.example.com/script.js',
+      websiteId: 'website-id',
+    });
+
+    const track = jest.fn();
+    window.umami = { track };
+    document.querySelector('script')?.dispatchEvent(new Event('load'));
+
+    expect(track).toHaveBeenCalledWith(
+      'competition_viewed',
+      expect.objectContaining({
+        app: 'competitiongroups',
+        auth_status: 'anonymous',
+        competition_id: 'ExampleComp2026',
+        page: 'groups',
+      }),
+    );
+  });
+
   it('tracks event data with shared app and auth properties', () => {
     const track = jest.fn();
     window.umami = { track };
@@ -85,4 +119,28 @@ describe('analytics', () => {
       }),
     );
   });
+
+  it('identifies logged-in users after the Umami script loads', () => {
+    loadUmamiScript({
+      src: 'https://analytics.example.com/script.js',
+      websiteId: 'website-id',
+    });
+
+    identifyUser(123);
+
+    const identify = jest.fn();
+    window.umami = {
+      identify,
+      track: jest.fn(),
+    };
+    document.querySelector('script')?.dispatchEvent(new Event('load'));
+
+    expect(identify).toHaveBeenCalledWith(
+      '123',
+      expect.objectContaining({
+        app: 'competitiongroups',
+        auth_status: 'logged_in',
+      }),
+    );
+  });
 });

src/lib/analytics.ts

@@ -8,11 +8,19 @@ type UmamiTrack = {
     ((data: AnalyticsProperties) => void);
 };
 
+type PendingEvent = {
+  eventName: string;
+  properties?: AnalyticsProperties;
+};
+
 const APP_NAME = 'competitiongroups';
 const MAX_EVENT_NAME_LENGTH = 50;
+const MAX_PENDING_EVENTS = 50;
 const UMAMI_SCRIPT_ID = 'umami-analytics-script';
 
 let currentUserId: string | undefined;
+let pendingEvents: PendingEvent[] = [];
+let umamiConfigured = false;
 
 const getEnvironment = () => (typeof __APP_ENV__ === 'undefined' ? 'test' : __APP_ENV__);
 
@@ -67,14 +75,80 @@ const eventProperties = (properties: AnalyticsProperties = {}): AnalyticsPropert
 export const isValidEventName = (eventName: string) =>
   eventName.length > 0 && eventName.length <= MAX_EVENT_NAME_LENGTH;
 
+export const configureUmamiAnalytics = ({
+  src,
+  websiteId,
+}: {
+  src?: string;
+  websiteId?: string;
+} = {}) => {
+  umamiConfigured = Boolean(src && websiteId);
+};
+
+const sendEvent = (eventName: string, properties?: AnalyticsProperties) => {
+  const umami = getUmami();
+  if (!umami?.track) {
+    return false;
+  }
+
+  umami.track(eventName, eventProperties(properties));
+  return true;
+};
+
+const queueEvent = (eventName: string, properties?: AnalyticsProperties) => {
+  if (!umamiConfigured) {
+    return;
+  }
+
+  pendingEvents = [...pendingEvents.slice(-(MAX_PENDING_EVENTS - 1)), { eventName, properties }];
+};
+
+const identifyCurrentUser = () => {
+  const umami = getUmami();
+  if (!umami?.identify || !currentUserId) {
+    return false;
+  }
+
+  umami.identify(currentUserId, {
+    ...baseProperties(),
+    auth_status: 'logged_in',
+  });
+  return true;
+};
+
+const flushPendingEvents = () => {
+  if (!pendingEvents.length) {
+    identifyCurrentUser();
+    return;
+  }
+
+  const events = pendingEvents;
+  pendingEvents = [];
+
+  events.forEach(({ eventName, properties }) => {
+    if (!sendEvent(eventName, properties)) {
+      queueEvent(eventName, properties);
+    }
+  });
+
+  identifyCurrentUser();
+};
+
 export const loadUmamiScript = ({
   src,
   websiteId,
 }: {
   src?: string;
   websiteId?: string;
 } = {}) => {
-  if (!isBrowser() || !src || !websiteId || document.getElementById(UMAMI_SCRIPT_ID)) {
+  if (!isBrowser() || !src || !websiteId) {
+    return;
+  }
+
+  configureUmamiAnalytics({ src, websiteId });
+
+  if (document.getElementById(UMAMI_SCRIPT_ID)) {
+    flushPendingEvents();
     return;
   }
 
@@ -83,21 +157,13 @@ export const loadUmamiScript = ({
   script.defer = true;
   script.src = src;
   script.dataset.websiteId = websiteId;
+  script.addEventListener('load', flushPendingEvents);
   document.head.appendChild(script);
 };
 
 export const identifyUser = (userId?: number | string | null) => {
   currentUserId = userId ? String(userId) : undefined;
-
-  const umami = getUmami();
-  if (!umami?.identify || !currentUserId) {
-    return;
-  }
-
-  umami.identify(currentUserId, {
-    ...baseProperties(),
-    auth_status: 'logged_in',
-  });
+  identifyCurrentUser();
 };
 
 export const trackEvent = (eventName: string, properties?: AnalyticsProperties) => {
@@ -108,12 +174,9 @@ export const trackEvent = (eventName: string, properties?: AnalyticsProperties)
     return;
   }
 
-  const umami = getUmami();
-  if (!umami?.track) {
-    return;
+  if (!sendEvent(eventName, properties)) {
+    queueEvent(eventName, properties);
   }
-
-  umami.track(eventName, eventProperties(properties));
 };
 
 export const trackCompetitionEvent = (
@@ -133,3 +196,9 @@ declare global {
     umami?: UmamiTrack;
   }
 }
+
+export const __resetAnalyticsForTests = () => {
+  currentUserId = undefined;
+  pendingEvents = [];
+  umamiConfigured = false;
+};