Issue LIF-Initiative#853: Add GA4 analytics instrumentation to Advisor and MDR frontends (LIF-Initiative#875)

bjagg · web-flow · commit 0ac1caa171e2 · 2026-03-20T08:08:47.000-07:00
##### Description of Change Adds Google Analytics 4 (GA4) instrumentation to both the Advisor and MDR frontends to provide visibility into who is visiting each app and how features are being used. **What problem does this solve?** Neither frontend has any analytics — there is no visibility into visitor traffic or feature usage. **What is the solution?** - A shared `analytics.ts` utility per frontend that conditionally loads gtag.js when `VITE_GA_MEASUREMENT_ID` is set at build time - Core event tracking calls added to key user actions in each app - Dockerfile updates to accept the measurement ID as a build arg **Advisor events (5):** `login`, `login_failed`, `conversation_started`, `message_sent`, `logout` **MDR events (5 + auto page_view):** `login`, `login_failed`, `model_selected`, `search_performed`, `mapping_opened` **Side effects / limitations:** - No analytics traffic in local dev (env var unset = complete no-op) - GA4 account/property/data streams must be created manually before deploy - No PII is sent in any event parameter **How should reviewers test this?** - Set `VITE_GA_MEASUREMENT_ID=G-XXXXXXXXXX` in a `.env.local` file and run either frontend - Verify gtag script loads in the browser network tab - Verify events appear in GA4 DebugView (Realtime > DebugView) - Confirm no gtag script or network requests when the env var is unset ##### Related Issues Closes LIF-Initiative#853 Closes LIF-Initiative#867 ##### Type of Change - [x] New feature (non-breaking change which adds functionality) - [x] Infrastructure/deployment change ##### Project Area(s) Affected - [x] frontends/ --- ##### Checklist - [x] commit message follows commit guidelines (see commitlint.config.mjs) - [x] documentation is changed or added (in /docs directory) - [x] pre-commit hooks have been run successfully ##### Testing - [ ] Manual testing performed - [ ] Automated tests added/updated - [ ] Integration testing completed ##### Additional Notes **Remaining manual steps before deploy:** 1. Create GA4 account, property, and two web data streams (Advisor + MDR) 2. Add `GA_MEASUREMENT_ID` build arg to CI/CD or Docker build commands 3. Share GA4 property access (Unicon = Editor, client = Viewer) See `docs/ga4-implementation-notes.md` and `docs/proposals/ga-analytics-instrumentation.md` for the full design doc and implementation notes. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
diff --git a/.github/workflows/lif_advisor_app.yml b/.github/workflows/lif_advisor_app.yml
@@ -57,6 +57,7 @@ jobs:
         ecr-repository: ${{ env.ECR_REPOSITORY }}
         build-args: |
           LIF_ADVISOR_API_URL=https://advisor-api.dev.lif.unicon.net
+          GA_MEASUREMENT_ID=G-WCYGBK4XHK
 
     - name: Update the lif-advisor-app ECS Service
       uses: ./.github/actions/update-cluster
diff --git a/.github/workflows/lif_mdr_frontend.yml b/.github/workflows/lif_mdr_frontend.yml
@@ -47,6 +47,7 @@ jobs:
       run: |
         npm ci
         echo "VITE_API_URL=https://mdr-api.${{ env.ENV_NAME }}.${{ env.DOMAIN }}" > .env
+        echo "VITE_GA_MEASUREMENT_ID=G-VZ515ZL70E" >> .env
         npm run build
 
     - name: Sync to S3
diff --git a/frontends/lif_advisor_app/Dockerfile b/frontends/lif_advisor_app/Dockerfile
@@ -1,9 +1,11 @@
 # Stage 1: build the vite application
 FROM node:20-alpine AS build
 
-# Accept a build-time argument for the API URL
+# Accept build-time arguments
 ARG LIF_ADVISOR_API_URL
 ENV LIF_ADVISOR_API_URL=${LIF_ADVISOR_API_URL}
+ARG GA_MEASUREMENT_ID
+ENV GA_MEASUREMENT_ID=${GA_MEASUREMENT_ID}
 
 # Set working directory
 WORKDIR /app
@@ -15,8 +17,9 @@ RUN apk update && apk upgrade && npm ci
 # Copy the rest of the application
 COPY . .
 
-# Inject Vite environment variable and build
+# Inject Vite environment variables and build
 RUN echo "VITE_LIF_ADVISOR_API_URL=${LIF_ADVISOR_API_URL}" > .env && \
+    echo "VITE_GA_MEASUREMENT_ID=${GA_MEASUREMENT_ID}" >> .env && \
     npm run build
 
 # Stage 2: serve the built app with nginx
diff --git a/frontends/lif_advisor_app/src/components/ChatInterface.tsx b/frontends/lif_advisor_app/src/components/ChatInterface.tsx
@@ -4,6 +4,7 @@ import MessageInput from './MessageInput';
 import { useChat } from '../hooks/useChat';
 import { BarChart3, Search, LogOut } from 'lucide-react';
 import { UserDetails } from '../types';
+import { trackLogout } from '../utils/analytics';
 
 interface ChatInterfaceProps {
   onLogout: () => void;
@@ -21,6 +22,7 @@ const ChatInterface: React.FC<ChatInterfaceProps> = ({ onLogout, user }) => {
   const handleLogout = async () => {
     if (isUserActionsDisabled) return;
     setLoggingOut(true);
+    trackLogout();
     displayLoggingOutMessage();
     await onLogout();
   };
diff --git a/frontends/lif_advisor_app/src/components/LoginPanel.tsx b/frontends/lif_advisor_app/src/components/LoginPanel.tsx
@@ -3,6 +3,7 @@ import axios from 'axios';
 import axiosInstance from '../utils/axios';
 import { KeyRound, User } from 'lucide-react';
 import { UserDetails } from '../types';
+import { trackLogin, trackLoginFailed } from '../utils/analytics';
 
 interface LoginPanelProps {
   onLoginSuccess: (user: UserDetails) => void;
@@ -40,10 +41,12 @@ const LoginPanel: React.FC<LoginPanelProps> = ({ onLoginSuccess }) => {
       if (response.data.success) {
         localStorage.setItem('token', response.data.access_token);
         localStorage.setItem('refreshToken', response.data.refresh_token);
+        trackLogin('password');
         onLoginSuccess(response.data.user);
       }
     } catch (error) {
       if (!axios.isCancel(error)) {
+        trackLoginFailed('password');
         setError('Invalid credentials. Please try again.');
       }
     } finally {
diff --git a/frontends/lif_advisor_app/src/hooks/useChat.ts b/frontends/lif_advisor_app/src/hooks/useChat.ts
@@ -3,6 +3,7 @@ import { Message } from '../types';
 import { generateId, delay } from '../utils/helpers';
 import axios from 'axios';
 import axiosInstance from '../utils/axios';
+import { trackEvent } from '../utils/analytics';
 
 export const useChat = () => {
   const [messages, setMessages] = useState<Message[]>([]);
@@ -81,6 +82,7 @@ export const useChat = () => {
         if (isMounted) {
           setIsTyping(false);
           setIsInitializing(false);
+          trackEvent('conversation_started');
         }
       }
     };
@@ -104,6 +106,7 @@ export const useChat = () => {
     };
 
     setMessages(prev => [...prev, userMessage]);
+    trackEvent('message_sent');
 
     const typingMessage: Message = {
       id: generateId(),
diff --git a/frontends/lif_advisor_app/src/main.tsx b/frontends/lif_advisor_app/src/main.tsx
@@ -1,4 +1,5 @@
 import { createRoot } from 'react-dom/client';
+import './utils/analytics';
 import App from './App.tsx';
 import './index.css';
 
diff --git a/frontends/lif_advisor_app/src/utils/analytics.ts b/frontends/lif_advisor_app/src/utils/analytics.ts
@@ -0,0 +1,50 @@
+/**
+ * GA4 analytics utility. All calls are no-ops when gtag is not loaded
+ * (i.e., when VITE_GA_MEASUREMENT_ID is not set).
+ */
+
+type GtagEventParams = Record<string, string | number | boolean>;
+
+const MEASUREMENT_ID = import.meta.env.VITE_GA_MEASUREMENT_ID as string | undefined;
+
+function loadGtag(): void {
+  if (!MEASUREMENT_ID) return;
+
+  const script = document.createElement('script');
+  script.async = true;
+  script.src = `https://www.googletagmanager.com/gtag/js?id=${MEASUREMENT_ID}`;
+  document.head.appendChild(script);
+
+  window.dataLayer = window.dataLayer || [];
+  window.gtag = function gtag(...args: unknown[]) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (window.dataLayer as any[]).push(args);
+  };
+  window.gtag('js', new Date());
+  window.gtag('config', MEASUREMENT_ID, { anonymize_ip: true });
+}
+
+// Initialize on module load
+loadGtag();
+
+function gtag(...args: unknown[]): void {
+  if (typeof window.gtag === 'function') {
+    window.gtag(...args);
+  }
+}
+
+export function trackEvent(eventName: string, params?: GtagEventParams): void {
+  gtag('event', eventName, params);
+}
+
+export function trackLogin(method: string): void {
+  trackEvent('login', { method });
+}
+
+export function trackLoginFailed(method: string): void {
+  trackEvent('login_failed', { method });
+}
+
+export function trackLogout(): void {
+  trackEvent('logout');
+}
diff --git a/frontends/lif_advisor_app/src/vite-env.d.ts b/frontends/lif_advisor_app/src/vite-env.d.ts
@@ -1 +1,6 @@
 /// <reference types="vite/client" />
+
+interface Window {
+  gtag: (...args: unknown[]) => void;
+  dataLayer: unknown[];
+}
diff --git a/frontends/mdr-frontend/Dockerfile b/frontends/mdr-frontend/Dockerfile
@@ -1,9 +1,11 @@
 # Stage 1: build the vite application
 FROM node:20-alpine AS build
 
-# Accept a build-time argument for the API URL
+# Accept build-time arguments
 ARG LIF_MDR_API_URL
 ENV LIF_MDR_API_URL=${LIF_MDR_API_URL}
+ARG GA_MEASUREMENT_ID
+ENV GA_MEASUREMENT_ID=${GA_MEASUREMENT_ID}
 
 # Set working directory
 WORKDIR /app
@@ -15,8 +17,9 @@ RUN apk update && apk upgrade && npm ci
 # Copy the rest of the application
 COPY . .
 
-# Inject Vite environment variable and build
+# Inject Vite environment variables and build
 RUN echo "VITE_API_URL=${LIF_MDR_API_URL}" > .env && \
+    echo "VITE_GA_MEASUREMENT_ID=${GA_MEASUREMENT_ID}" >> .env && \
     npm run build
 
 # Stage 2: serve the built app with nginx
diff --git a/frontends/mdr-frontend/src/components/DataModelSelector/DataModelSelector.tsx b/frontends/mdr-frontend/src/components/DataModelSelector/DataModelSelector.tsx
@@ -6,6 +6,7 @@ import { SimpleTree, transformData } from "./SimpleTree";
 import { CrudDialog } from "../Dialog/Dialog";
 import ModelTree from "../ModelExplorer/ModelExplorer";
 import { errorToString } from "../../utils/errorUtils";
+import { trackEvent } from "../../utils/analytics";
 
 const FileDEBUG = false;
 const debugLog = (...args: any[]) => { if(FileDEBUG) console.log(...args); };
@@ -44,6 +45,10 @@ const DataModelSelector: React.FC<ExplorePageLayoutProps> = ({
       console.warn("Model not found for ID:", id);
       return;
     }
+    trackEvent('model_selected', {
+      model_id: String(id),
+      model_type: model.Type ?? 'unknown',
+    });
     model.urlParam = extraPath;
     setModelPath(path);
     setSelectedModel(model);
diff --git a/frontends/mdr-frontend/src/main.tsx b/frontends/mdr-frontend/src/main.tsx
@@ -4,6 +4,7 @@ import { RouterProvider } from "react-router-dom";
 import { MdrProvider } from "./context/MdrContext";
 import { AuthProvider } from "./context/AuthContext";
 import router from "./pages/Routes";
+import "./utils/analytics";
 import "./index.css";
 import "@radix-ui/themes/styles.css";
 
diff --git a/frontends/mdr-frontend/src/pages/Explore/ExploreSearch.tsx b/frontends/mdr-frontend/src/pages/Explore/ExploreSearch.tsx
@@ -3,13 +3,15 @@ import { Box, Card, Flex, Separator, Text } from "@radix-ui/themes";
 import { useNavigate, useSearchParams } from "react-router-dom";
 import { searchAll } from "../../services/searchService";
 import { getAttributeEntityAssociationsByAttr } from "../../services/attributesService";
+import { trackEvent } from "../../utils/analytics";
 
 const ExploreSearch: React.FC = () => {
     const [params] = useSearchParams();
     const [searchResults, setSearchResults] = useState<any>(null);
     const navigate = useNavigate();
 
     const fetchSearchResults = async (keyword: string) => {
+        trackEvent('search_performed', { search_term: keyword });
         const results = await searchAll(keyword);
         console.log("results", results);
         setSearchResults(results);
diff --git a/frontends/mdr-frontend/src/pages/Explore/Mappings/MappingsView.tsx b/frontends/mdr-frontend/src/pages/Explore/Mappings/MappingsView.tsx
@@ -60,6 +60,7 @@ import EditGroupDialog from './components/EditGroupDialog';
 import ForkGroupDialog from './components/ForkGroupDialog';
 import DetachSourcesDialog from './components/DetachSourcesDialog';
 import BulkTransformationsDialog from './components/BulkTransformationsDialog';
+import { trackEvent } from '../../../utils/analytics';
 
 interface DisplayTransformationData extends TransformationData {
     SourceEntity?: EntityDTO;
@@ -648,6 +649,7 @@ const MappingsView: React.FC = () => {
         if (groupIdParam != null) {
             const id = parseInt(groupIdParam, 10);
             if (!isNaN(id)) {
+                trackEvent('mapping_opened', { group_id: String(id) });
                 setGroupId(id);
                 setError(null);
             } else {
diff --git a/frontends/mdr-frontend/src/pages/Login.tsx b/frontends/mdr-frontend/src/pages/Login.tsx
@@ -1,6 +1,7 @@
 import React, { useState, useEffect } from "react";
 import { Navigate, useLocation } from "react-router-dom";
 import authService from "../services/authService";
+import { trackLogin, trackLoginFailed } from "../utils/analytics";
 import {
   Box,
   Card,
@@ -42,10 +43,12 @@ const Login: React.FC = () => {
 
     try {
       await authService.login({ username, password });
+      trackLogin('password');
       // Redirect to the intended page or home
       const from = location.state?.from?.pathname || "/";
       window.location.href = from;
     } catch (error) {
+      trackLoginFailed('password');
       setError("Invalid username or password");
     } finally {
       setIsLoading(false);
diff --git a/frontends/mdr-frontend/src/utils/analytics.ts b/frontends/mdr-frontend/src/utils/analytics.ts
@@ -0,0 +1,50 @@
+/**
+ * GA4 analytics utility. All calls are no-ops when gtag is not loaded
+ * (i.e., when VITE_GA_MEASUREMENT_ID is not set).
+ */
+
+type GtagEventParams = Record<string, string | number | boolean>;
+
+const MEASUREMENT_ID = import.meta.env.VITE_GA_MEASUREMENT_ID as string | undefined;
+
+function loadGtag(): void {
+  if (!MEASUREMENT_ID) return;
+
+  const script = document.createElement('script');
+  script.async = true;
+  script.src = `https://www.googletagmanager.com/gtag/js?id=${MEASUREMENT_ID}`;
+  document.head.appendChild(script);
+
+  window.dataLayer = window.dataLayer || [];
+  window.gtag = function gtag(...args: unknown[]) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (window.dataLayer as any[]).push(args);
+  };
+  window.gtag('js', new Date());
+  window.gtag('config', MEASUREMENT_ID, { anonymize_ip: true });
+}
+
+// Initialize on module load
+loadGtag();
+
+function gtag(...args: unknown[]): void {
+  if (typeof window.gtag === 'function') {
+    window.gtag(...args);
+  }
+}
+
+export function trackEvent(eventName: string, params?: GtagEventParams): void {
+  gtag('event', eventName, params);
+}
+
+export function trackLogin(method: string): void {
+  trackEvent('login', { method });
+}
+
+export function trackLoginFailed(method: string): void {
+  trackEvent('login_failed', { method });
+}
+
+export function trackLogout(): void {
+  trackEvent('logout');
+}
diff --git a/frontends/mdr-frontend/src/vite-env.d.ts b/frontends/mdr-frontend/src/vite-env.d.ts
@@ -1 +1,6 @@
 /// <reference types="vite/client" />
+
+interface Window {
+  gtag: (...args: unknown[]) => void;
+  dataLayer: unknown[];
+}
diff --git a/scripts/release-demo-frontend.sh b/scripts/release-demo-frontend.sh
@@ -18,6 +18,7 @@ AWS_REGION=us-east-1
 S3_BUCKET=""  # Resolved after AWS credentials are verified
 SSM_DISTRIBUTION_ID="/${ENV_NAME}/${SERVICE_NAME}/DistributionId"
 VITE_API_URL="https://mdr-api.${ENV_NAME}.lif.unicon.net"
+GA_MEASUREMENT_ID="G-VZ515ZL70E"
 FRONTEND_DIR="frontends/mdr-frontend"
 
 # Colors
@@ -226,6 +227,7 @@ build_frontend() {
 
     log_info "Building with VITE_API_URL=$VITE_API_URL..."
     echo "VITE_API_URL=$VITE_API_URL" > "$build_dir/.env"
+    echo "VITE_GA_MEASUREMENT_ID=$GA_MEASUREMENT_ID" >> "$build_dir/.env"
     (cd "$build_dir" && npm run build --silent) || {
         log_error "npm run build failed"
         exit 1

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`import { createRoot } from 'react-dom/client';`
	`2`	`+import './utils/analytics';`
`2`	`3`	`import App from './App.tsx';`
`3`	`4`	`import './index.css';`
`4`	`5`