Analytics Helpers

User behavior tracking and analytics utilities using Segment, Userpilot, and Intercom for the WorkPayCore frontend application.

Overview

The analytics helpers provide a unified interface for user tracking, event analytics, and customer engagement across multiple platforms.

Core Functions

analyticsIdentifyUser(userId, traits)

Identifies a user across all analytics platforms with their profile information.

Parameters:

• userId (string): Unique identifier for the user
• traits (Record<string, any>): User traits and metadata

Returns:

• void: No return value

Example:

import { analyticsIdentifyUser } from '@/utils/helpers/analytics';

// Identify user on login
const handleLogin = user => {
  analyticsIdentifyUser(user.id, {
    name: `${user.firstName} ${user.lastName}`,
    email: user.email,
    role: user.role,
    createdAt: user.createdAt,
    company: {
      id: user.companyId,
      name: user.companyName,
      industry: user.companyIndustry,
      size: user.companySize,
    },
  });
};

Use Cases:

• User authentication tracking
• Profile information sync
• Cross-platform user identification
• Company grouping

---

analyticsTrackEvent(event, properties?)

Tracks user actions and events with optional metadata.

Parameters:

• event (AnalyticsEvents): The event name from the events enum
• properties (Record<string, any>, optional): Additional event metadata

Returns:

• void: No return value

Example:

import { analyticsTrackEvent } from '@/utils/helpers/analytics';
import { AnalyticsEvents } from '@/utils/helpers/analytics/events';

// Track button click
analyticsTrackEvent(AnalyticsEvents.BUTTON_CLICKED, {
  buttonName: 'Create Employee',
  page: 'employees',
  section: 'header',
});

// Track form submission
analyticsTrackEvent(AnalyticsEvents.FORM_SUBMITTED, {
  formName: 'employee-creation',
  fields: ['name', 'email', 'department'],
  success: true,
});

// Track feature usage
analyticsTrackEvent(AnalyticsEvents.FEATURE_USED, {
  feature: 'payroll-calculator',
  duration: 120, // seconds
  result: 'completed',
});

Use Cases:

• User interaction tracking
• Feature usage analytics
• Conversion funnel analysis
• Error tracking

---

analyticsLogPage(name, properties?)

Logs page views and navigation events.

Parameters:

• name (string): The page name or identifier
• properties (Record<string, any>, optional): Page metadata

Returns:

• void: No return value

Example:

import { analyticsLogPage } from '@/utils/helpers/analytics';

// Track page view
const Dashboard = () => {
  useEffect(() => {
    analyticsLogPage('Dashboard', {
      section: 'main',
      userRole: 'admin',
      companySize: 'medium',
    });
  }, []);

  return <div>Dashboard Content</div>;
};

// Track navigation with context
const handleNavigate = page => {
  analyticsLogPage(page, {
    previousPage: location.pathname,
    navigationMethod: 'sidebar',
    timestamp: Date.now(),
  });
};

Use Cases:

• Page view tracking
• Navigation pattern analysis
• User journey mapping
• Performance monitoring

---

analyticsGroupUser(groupId, traits)

Associates a user with a company or organization group.

Parameters:

• groupId (string): Unique identifier for the group/company
• traits (Record<string, any>): Group/company metadata

Returns:

• void: No return value

Example:

import { analyticsGroupUser } from '@/utils/helpers/analytics';

// Group user by company
analyticsGroupUser('company-123', {
  name: 'Acme Corporation',
  industry: 'Technology',
  employees: 500,
  plan: 'enterprise',
  subscription: 'annual',
});

Use Cases:

• Company-level analytics
• Group behavior analysis
• B2B feature tracking
• Subscription analytics

---

analyticsReset()

Resets analytics state when a user logs out.

Parameters:

• None

Returns:

• void: No return value

Example:

import { analyticsReset } from '@/utils/helpers/analytics';

const handleLogout = () => {
  // Clear analytics data
  analyticsReset();

  // Clear local storage
  localStorage.clear();

  // Redirect to login
  navigate('/login');
};

Use Cases:

• User logout cleanup
• Session termination
• Privacy compliance
• Data isolation

---

reloadUserPilot()

Reloads Userpilot for updated guided tours and onboarding flows.

Parameters:

• None

Returns:

• void: No return value

Example:

import { reloadUserPilot } from '@/utils/helpers/analytics';

// Reload on route change
const useUserPilotReload = () => {
  const location = useLocation();

  useEffect(() => {
    reloadUserPilot();
  }, [location.pathname, location.search]);
};

// Reload after feature flag changes
const useFeatureFlagReload = () => {
  const featureFlags = useFeatureFlags();

  useEffect(() => {
    reloadUserPilot();
  }, [featureFlags]);
};

Use Cases:

• URL change handling
• Feature flag updates
• Onboarding flow updates
• User guidance refresh

---

Advanced Usage Examples

React Hook for Analytics

import {
  analyticsTrackEvent,
  analyticsLogPage,
} from '@/utils/helpers/analytics';

const useAnalytics = () => {
  const trackEvent = useCallback((event, properties = {}) => {
    analyticsTrackEvent(event, {
      ...properties,
      timestamp: Date.now(),
      userAgent: navigator.userAgent,
    });
  }, []);

  const trackPage = useCallback((pageName, properties = {}) => {
    analyticsLogPage(pageName, {
      ...properties,
      referrer: document.referrer,
      timestamp: Date.now(),
    });
  }, []);

  return { trackEvent, trackPage };
};

// Usage in component
const EmployeeList = () => {
  const { trackEvent, trackPage } = useAnalytics();

  useEffect(() => {
    trackPage('Employee List');
  }, [trackPage]);

  const handleCreateEmployee = () => {
    trackEvent(AnalyticsEvents.BUTTON_CLICKED, {
      action: 'create_employee',
      location: 'employee_list',
    });
  };

  return (
    <div>
      <button onClick={handleCreateEmployee}>Create Employee</button>
    </div>
  );
};

Form Analytics

import { analyticsTrackEvent } from '@/utils/helpers/analytics';

const useFormAnalytics = formName => {
  const trackFormStart = () => {
    analyticsTrackEvent(AnalyticsEvents.FORM_STARTED, {
      formName,
      timestamp: Date.now(),
    });
  };

  const trackFormError = errors => {
    analyticsTrackEvent(AnalyticsEvents.FORM_ERROR, {
      formName,
      errors: Object.keys(errors),
      errorCount: Object.keys(errors).length,
    });
  };

  const trackFormSubmit = data => {
    analyticsTrackEvent(AnalyticsEvents.FORM_SUBMITTED, {
      formName,
      fieldCount: Object.keys(data).length,
      completionTime: Date.now() - formStartTime,
    });
  };

  return { trackFormStart, trackFormError, trackFormSubmit };
};

// Usage
const PayrollForm = () => {
  const { trackFormStart, trackFormError, trackFormSubmit } =
    useFormAnalytics('payroll-creation');

  const handleSubmit = (data, { setErrors }) => {
    if (errors) {
      trackFormError(errors);
      setErrors(errors);
      return;
    }

    trackFormSubmit(data);
    // Process form...
  };

  useEffect(() => {
    trackFormStart();
  }, []);

  return <form onSubmit={handleSubmit}>...</form>;
};

User Journey Tracking

import {
  analyticsTrackEvent,
  analyticsLogPage,
} from '@/utils/helpers/analytics';

const useUserJourney = () => {
  const [journeySteps, setJourneySteps] = useState([]);

  const addJourneyStep = (step, metadata = {}) => {
    const stepData = {
      step,
      timestamp: Date.now(),
      ...metadata,
    };

    setJourneySteps(prev => [...prev, stepData]);

    analyticsTrackEvent(AnalyticsEvents.JOURNEY_STEP, stepData);
  };

  const completeJourney = outcome => {
    analyticsTrackEvent(AnalyticsEvents.JOURNEY_COMPLETED, {
      steps: journeySteps,
      totalSteps: journeySteps.length,
      duration: Date.now() - journeySteps[0]?.timestamp,
      outcome,
    });

    setJourneySteps([]);
  };

  return { addJourneyStep, completeJourney, journeySteps };
};

// Usage for onboarding flow
const OnboardingFlow = () => {
  const { addJourneyStep, completeJourney } = useUserJourney();

  const handleStepComplete = stepName => {
    addJourneyStep(stepName, {
      progress: calculateProgress(),
      userInput: collectUserInput(),
    });
  };

  const handleOnboardingComplete = () => {
    completeJourney('success');
  };

  return <OnboardingWizard onStepComplete={handleStepComplete} />;
};

Feature Usage Analytics

import { analyticsTrackEvent } from '@/utils/helpers/analytics';

const useFeatureAnalytics = featureName => {
  const trackFeatureStart = (context = {}) => {
    analyticsTrackEvent(AnalyticsEvents.FEATURE_STARTED, {
      feature: featureName,
      ...context,
    });
  };

  const trackFeatureEnd = (outcome, metrics = {}) => {
    analyticsTrackEvent(AnalyticsEvents.FEATURE_COMPLETED, {
      feature: featureName,
      outcome,
      ...metrics,
    });
  };

  const trackFeatureError = error => {
    analyticsTrackEvent(AnalyticsEvents.FEATURE_ERROR, {
      feature: featureName,
      error: error.message,
      stack: error.stack,
    });
  };

  return { trackFeatureStart, trackFeatureEnd, trackFeatureError };
};

// Usage
const PayrollCalculator = () => {
  const { trackFeatureStart, trackFeatureEnd, trackFeatureError } =
    useFeatureAnalytics('payroll-calculator');

  const calculatePayroll = async () => {
    try {
      trackFeatureStart({
        employeeCount: employees.length,
        payPeriod: selectedPeriod,
      });

      const result = await performCalculation();

      trackFeatureEnd('success', {
        calculationTime: result.duration,
        totalAmount: result.total,
        employeesProcessed: result.count,
      });
    } catch (error) {
      trackFeatureError(error);
    }
  };

  return <button onClick={calculatePayroll}>Calculate</button>;
};

---

Error Handling

Safe Analytics Tracking

import { analyticsTrackEvent } from '@/utils/helpers/analytics';

const safeTrackEvent = (event, properties = {}) => {
  try {
    analyticsTrackEvent(event, properties);
  } catch (error) {
    console.error('Analytics tracking failed:', error);
    // Continue execution without breaking the user experience
  }
};

// Usage
const handleButtonClick = () => {
  safeTrackEvent(AnalyticsEvents.BUTTON_CLICKED, {
    buttonName: 'submit',
  });

  // Continue with main functionality
  processForm();
};

---

Integration with Other Services

Automatic URL and Search Tracking

All analyticsTrackEvent calls automatically include:

• url: Current page URL
• search: Current URL search parameters

Cross-Platform Synchronization

The identify function automatically syncs user data across:

• Segment: Primary analytics platform
• Userpilot: User onboarding and guidance
• Intercom: Customer support and messaging

---

Environment Configuration

Required Environment Variables

# .env file
VITE_SEGMENT_WRITE_KEY=your_segment_write_key
VITE_INTERCOM_APP_ID=your_intercom_app_id
VITE_USERPILOT_TOKEN=your_userpilot_token

---

Best Practices

1. Consistent Events: Use predefined event names from AnalyticsEvents
2. Meaningful Properties: Include relevant context in event properties
3. User Privacy: Respect user consent and privacy settings
4. Error Handling: Wrap analytics calls in try-catch blocks
5. Performance: Avoid tracking too frequently or with large payloads

---

Related Utilities

• Feature Flag Helpers - For feature-based analytics
• General Helpers - For common utilities

---

TypeScript Definitions

import { AnalyticsEvents } from './events';

export function analyticsIdentifyUser(
  userId: string,
  traits: Record<string, any>,
): void;

export function analyticsTrackEvent(
  event: AnalyticsEvents,
  properties?: Record<string, any>,
): void;

export function analyticsLogPage(
  name: string,
  properties?: Record<string, any>,
): void;

export function analyticsGroupUser(
  groupId: string,
  traits: Record<string, any>,
): void;

export function analyticsReset(): void;
export function reloadUserPilot(): void;

---

Dependencies

• @segment/analytics-next: Segment analytics SDK
• userpilot: User onboarding platform
• @intercom/messenger-js-sdk: Intercom customer messaging
• Environment variables: For API keys and tokens