@trustchex/react-native-sdk 1.253.0 → 1.266.0

package/src/Shared/Libs/analytics.utils.ts

@@ -0,0 +1,644 @@
+/**
+ * Analytics Helper Utilities
+ * Convenience functions for common analytics tracking patterns
+ * All functions handle errors silently to prevent blocking application flow
+ */
+
+import { useEffect, useState } from 'react';
+import { analyticsService } from '../Services/AnalyticsService';
+import {
+  AnalyticsEventCategory,
+  AnalyticsEventName,
+} from '../Types/analytics.types';
+import type { AnalyticsEventMetadata, ErrorSeverity, ErrorContext } from '../Types/analytics.types';
+
+/**
+ * Track screen view event
+ */
+export const trackScreenView = async (
+  screenName: string,
+  previousScreen?: string
+) => {
+  try {
+    await analyticsService.trackEvent(
+      AnalyticsEventName.SCREEN_VIEW,
+      AnalyticsEventCategory.NAVIGATION,
+      {
+        screenName,
+        previousScreen,
+      }
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+/**
+ * Track screen exit with duration
+ */
+export const trackScreenExit = async (
+  screenName: string,
+  durationMs: number
+) => {
+  try {
+    await analyticsService.trackEvent(
+      AnalyticsEventName.SCREEN_EXIT,
+      AnalyticsEventCategory.NAVIGATION,
+      {
+        screenName,
+        duration: durationMs,
+      }
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+/**
+ * Track button click
+ */
+export const trackButtonClick = async (
+  buttonName: string,
+  screenName: string,
+  metadata?: AnalyticsEventMetadata
+) => {
+  try {
+    await analyticsService.trackEvent(
+      AnalyticsEventName.BUTTON_CLICK,
+      AnalyticsEventCategory.USER_ACTION,
+      {
+        buttonName,
+        screenName,
+        ...metadata,
+      }
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+/**
+ * Sanitize stack trace to remove PII and file paths
+ */
+const sanitizeStackTrace = (error: Error): string | undefined => {
+  if (!error.stack) return undefined;
+  try {
+    // Keep only function names and line numbers, remove file paths
+    const lines = error.stack.split('\n').slice(0, 5);
+    return lines
+      .map(line => {
+        // Remove full file paths, keep just the filename and line
+        return line.replace(/\(.*\/([^/]+:[0-9]+:[0-9]+)\)/, '($1)')
+                   .replace(/at\s+.*\/([^/]+)/, 'at $1')
+                   .trim();
+      })
+      .join(' -> ');
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Infer error category from error code
+ */
+const inferErrorCategory = (errorCode: string): string => {
+  const code = errorCode.toLowerCase();
+  if (code.includes('network') || code.includes('fetch') || code.includes('timeout')) return 'network';
+  if (code.includes('permission') || code.includes('denied')) return 'permission';
+  if (code.includes('camera')) return 'camera';
+  if (code.includes('nfc') || code.includes('eid')) return 'nfc';
+  if (code.includes('validation') || code.includes('invalid')) return 'validation';
+  if (code.includes('api') || code.includes('response') || code.includes('status')) return 'api';
+  if (code.includes('storage') || code.includes('file') || code.includes('save')) return 'storage';
+  if (code.includes('device')) return 'device';
+  if (code.includes('input') || code.includes('user')) return 'user_input';
+  return 'unknown';
+};
+
+/**
+ * Track error event with unique event name per error code
+ * Event name format: error_{errorCode} (e.g., error_camera_permission_denied)
+ * 
+ * Only errors with severity 'medium' or higher are recorded.
+ * Low severity errors are ignored to reduce noise.
+ * 
+ * @param errorCode - Unique identifier for the error type
+ * @param errorMessage - Human-readable error message (sanitized)
+ * @param screenName - Screen where the error occurred
+ * @param severity - Error severity level: 'low' | 'medium' | 'high' | 'critical'
+ * @param context - Optional additional context for the error
+ */
+export const trackError = async (
+  errorCode: string,
+  errorMessage: string,
+  screenName: string,
+  severity: 'low' | 'medium' | 'high' | 'critical' = 'medium',
+  context?: {
+    error?: Error;
+    component?: string;
+    userAction?: string;
+    recoverable?: boolean;
+    retryCount?: number;
+    category?: string;
+    additionalData?: Record<string, string | number | boolean | null>;
+  }
+) => {
+  try {
+    // Only track errors with severity medium or higher
+    // Low severity errors are expected/recoverable and create noise
+    if (severity === 'low') {
+      return;
+    }
+
+    // Create unique event name per error code
+    const eventName = `error_${errorCode.toLowerCase().replace(/[^a-z0-9]/g, '_')}`;
+
+    // Build metadata with all available context
+    const metadata: AnalyticsEventMetadata = {
+      errorCode,
+      errorMessage,
+      screenName,
+      severity,
+      category: context?.category || inferErrorCategory(errorCode),
+    };
+
+    // Add optional context fields
+    if (context?.component) metadata.component = context.component;
+    if (context?.userAction) metadata.userAction = context.userAction;
+    if (context?.recoverable !== undefined) metadata.recoverable = context.recoverable;
+    if (context?.retryCount !== undefined) metadata.retryCount = context.retryCount;
+    
+    // Add sanitized stack trace if error object provided
+    if (context?.error) {
+      const stackTrace = sanitizeStackTrace(context.error);
+      if (stackTrace) metadata.stackTrace = stackTrace;
+    }
+
+    // Merge additional data
+    if (context?.additionalData) {
+      Object.entries(context.additionalData).forEach(([key, value]) => {
+        metadata[key] = value;
+      });
+    }
+
+    await analyticsService.trackEvent(
+      eventName,
+      AnalyticsEventCategory.ERROR,
+      metadata
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+/**
+ * Track error with full Error object for automatic stack trace extraction
+ */
+export const trackErrorWithDetails = async (
+  error: Error,
+  errorCode: string,
+  screenName: string,
+  severity: 'low' | 'medium' | 'high' | 'critical' = 'medium',
+  context?: {
+    component?: string;
+    userAction?: string;
+    recoverable?: boolean;
+    retryCount?: number;
+    category?: string;
+    additionalData?: Record<string, string | number | boolean | null>;
+  }
+) => {
+  return trackError(
+    errorCode,
+    error.message || 'Unknown error',
+    screenName,
+    severity,
+    { ...context, error }
+  );
+};
+
+/**
+ * Track API call performance
+ */
+export const trackApiCall = async (
+  endpoint: string,
+  durationMs: number,
+  statusCode: number,
+  success: boolean
+) => {
+  try {
+    await analyticsService.trackEvent(
+      AnalyticsEventName.API_CALL_DURATION,
+      AnalyticsEventCategory.PERFORMANCE,
+      {
+        endpoint,
+        duration: durationMs,
+        statusCode,
+        success,
+      }
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+/**
+ * Map workflow step types to valid analytics event names
+ */
+const STEP_EVENT_MAP: Record<string, { started: AnalyticsEventName; completed: AnalyticsEventName }> = {
+  contract_acceptance: {
+    started: AnalyticsEventName.CONTRACT_ACCEPTANCE_STARTED,
+    completed: AnalyticsEventName.CONTRACT_ACCEPTANCE_COMPLETED,
+  },
+  identity_document_scan: {
+    started: AnalyticsEventName.DOCUMENT_SCAN_STARTED,
+    completed: AnalyticsEventName.DOCUMENT_SCAN_COMPLETED,
+  },
+  identity_document_eid_scan: {
+    started: AnalyticsEventName.IDENTITY_DOCUMENT_EID_SCAN_STARTED,
+    completed: AnalyticsEventName.IDENTITY_DOCUMENT_EID_SCAN_COMPLETED,
+  },
+  liveness_check: {
+    started: AnalyticsEventName.LIVENESS_CHECK_STARTED,
+    completed: AnalyticsEventName.LIVENESS_CHECK_COMPLETED,
+  },
+};
+
+function getStepEventName(stepType: string, suffix: 'started' | 'completed'): string {
+  const normalizedStep = stepType.toLowerCase();
+  const mapping = STEP_EVENT_MAP[normalizedStep];
+  if (mapping) {
+    return mapping[suffix];
+  }
+  // Fallback to dynamic name for unknown step types
+  return `${normalizedStep}_${suffix}`;
+}
+
+/**
+ * Track verification process events
+ */
+export const trackVerificationStart = async (
+  stepType: string
+) => {
+  try {
+    const eventName = getStepEventName(stepType, 'started');
+
+    await analyticsService.trackEvent(
+      eventName,
+      AnalyticsEventCategory.VERIFICATION,
+      {
+        stepType,
+      }
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+export const trackVerificationComplete = async (
+  stepType: string,
+  success: boolean,
+  attemptNumber?: number
+) => {
+  try {
+    const eventName = getStepEventName(stepType, 'completed');
+
+    await analyticsService.trackEvent(
+      eventName,
+      AnalyticsEventCategory.VERIFICATION,
+      {
+        stepType,
+        success,
+        attemptNumber,
+      }
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+/**
+ * Track session events
+ */
+export const trackSessionStart = async (sessionId: string) => {
+  try {
+    await analyticsService.trackEvent(
+      AnalyticsEventName.SESSION_START,
+      AnalyticsEventCategory.SESSION,
+      {
+        sessionId,
+      }
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+export const trackSessionEnd = async (sessionId: string, reason?: string) => {
+  try {
+    await analyticsService.trackEvent(
+      AnalyticsEventName.SESSION_END,
+      AnalyticsEventCategory.SESSION,
+      {
+        sessionId,
+        reason,
+      }
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+/**
+ * Track NFC scan events with detailed metadata
+ */
+export const trackNFCScanStart = async (
+  documentType: 'ID' | 'PASSPORT' | 'UNKNOWN',
+  nfcSupported: boolean,
+  nfcEnabled: boolean,
+  attemptNumber: number = 1
+) => {
+  try {
+    await analyticsService.trackEvent(
+      AnalyticsEventName.NFC_SCAN_STARTED,
+      AnalyticsEventCategory.VERIFICATION,
+      {
+        verificationType: 'nfc',
+        documentType,
+        nfcSupported,
+        nfcEnabled,
+        attemptNumber,
+      }
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+export const trackNFCScanComplete = async (
+  documentType: 'ID' | 'PASSPORT' | 'UNKNOWN',
+  scanDuration: number,
+  attemptNumber: number = 1
+) => {
+  try {
+    await analyticsService.trackEvent(
+      AnalyticsEventName.NFC_SCAN_COMPLETED,
+      AnalyticsEventCategory.VERIFICATION,
+      {
+        verificationType: 'nfc',
+        success: true,
+        documentType,
+        scanDuration,
+        attemptNumber,
+      }
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+export const trackNFCScanFailed = async (
+  documentType: 'ID' | 'PASSPORT' | 'UNKNOWN',
+  errorType:
+    | 'device_unsupported'
+    | 'not_enabled'
+    | 'reading_error'
+    | 'user_cancelled'
+    | 'timeout'
+    | 'unknown',
+  errorMessage: string,
+  scanDuration: number,
+  attemptNumber: number = 1,
+  deviceModel?: string,
+  osVersion?: string
+) => {
+  try {
+    const eventName =
+      errorType === 'device_unsupported'
+        ? AnalyticsEventName.NFC_DEVICE_UNSUPPORTED
+        : errorType === 'user_cancelled'
+          ? AnalyticsEventName.NFC_USER_CANCELLED
+          : errorType === 'reading_error'
+            ? AnalyticsEventName.NFC_READING_ERROR
+            : AnalyticsEventName.NFC_SCAN_FAILED;
+
+    await analyticsService.trackEvent(eventName, AnalyticsEventCategory.ERROR, {
+      verificationType: 'nfc',
+      success: false,
+      documentType,
+      errorType,
+      errorMessage,
+      scanDuration,
+      attemptNumber,
+      deviceModel,
+      osVersion,
+    });
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+/**
+ * EID (identity document with NFC) specific events
+ */
+export const trackEIDScanStart = async (
+  documentType: 'ID' | 'PASSPORT' | 'UNKNOWN',
+  nfcSupported: boolean,
+  nfcEnabled: boolean,
+  attemptNumber: number = 1
+) => {
+  try {
+    await analyticsService.trackEvent(
+      AnalyticsEventName.IDENTITY_DOCUMENT_EID_SCAN_STARTED,
+      AnalyticsEventCategory.VERIFICATION,
+      {
+        verificationType: 'nfc',
+        documentType,
+        nfcSupported,
+        nfcEnabled,
+        attemptNumber,
+      }
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+export const trackEIDScanComplete = async (
+  documentType: 'ID' | 'PASSPORT' | 'UNKNOWN',
+  scanDuration: number,
+  attemptNumber: number = 1
+) => {
+  try {
+    await analyticsService.trackEvent(
+      AnalyticsEventName.IDENTITY_DOCUMENT_EID_SCAN_COMPLETED,
+      AnalyticsEventCategory.VERIFICATION,
+      {
+        verificationType: 'nfc',
+        success: true,
+        documentType,
+        scanDuration,
+        attemptNumber,
+      }
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+export const trackEIDScanFailed = async (
+  documentType: 'ID' | 'PASSPORT' | 'UNKNOWN',
+  errorType:
+    | 'device_unsupported'
+    | 'not_enabled'
+    | 'reading_error'
+    | 'user_cancelled'
+    | 'timeout'
+    | 'unknown',
+  errorMessage: string,
+  scanDuration: number,
+  attemptNumber: number = 1,
+  deviceModel?: string,
+  osVersion?: string
+) => {
+  try {
+    await analyticsService.trackEvent(
+      AnalyticsEventName.IDENTITY_DOCUMENT_EID_SCAN_FAILED,
+      AnalyticsEventCategory.ERROR,
+      {
+        verificationType: 'nfc',
+        success: false,
+        documentType,
+        errorType,
+        errorMessage,
+        scanDuration,
+        attemptNumber,
+        deviceModel,
+        osVersion,
+      }
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+/**
+ * Track step abandonment
+ */
+export const trackStepAbandoned = async (
+  stepName: string,
+  stepIndex: number,
+  totalSteps: number,
+  timeOnStep: number
+) => {
+  try {
+    await analyticsService.trackEvent(
+      AnalyticsEventName.STEP_ABANDONED,
+      AnalyticsEventCategory.USER_ACTION,
+      {
+        stepName,
+        stepIndex,
+        totalSteps,
+        timeOnStep,
+        isRequired: true,
+      }
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+/**
+ * Track step skipped
+ */
+export const trackStepSkipped = async (
+  stepName: string,
+  stepIndex: number,
+  totalSteps: number,
+  previousStep?: string
+) => {
+  try {
+    await analyticsService.trackEvent(
+      AnalyticsEventName.STEP_SKIPPED,
+      AnalyticsEventCategory.USER_ACTION,
+      {
+        stepName,
+        stepIndex,
+        totalSteps,
+        previousStep,
+        isRequired: false,
+      }
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+/**
+ * Track consent/contract acceptance
+ */
+export const trackConsentGiven = async (
+  contractIds: string[],
+  screenName: string = 'contract_acceptance'
+) => {
+  try {
+    await analyticsService.trackEvent(
+      AnalyticsEventName.CONSENT_GIVEN,
+      AnalyticsEventCategory.USER_ACTION,
+      {
+        screenName,
+        contractIds: contractIds.join(','),
+        consentType: 'contract_acceptance',
+      }
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+/**
+ * Track funnel step progress
+ */
+export const trackFunnelStep = async (
+  stepName: string,
+  stepIndex: number,
+  totalSteps: number,
+  previousStep?: string,
+  isRequired: boolean = true
+) => {
+  try {
+    await analyticsService.trackEvent(
+      AnalyticsEventName.SCREEN_VIEW,
+      AnalyticsEventCategory.NAVIGATION,
+      {
+        screenName: stepName,
+        stepName,
+        stepIndex,
+        totalSteps,
+        previousStep,
+        isRequired,
+      }
+    );
+  } catch (error) {
+    // Silently fail - analytics should never block app flow
+  }
+};
+
+/**
+ * React hook for screen tracking
+ */
+export const useScreenTracking = (screenName: string) => {
+  const [screenStartTime] = useState(Date.now());
+
+  useEffect(() => {
+    // Track screen view on mount
+    trackScreenView(screenName);
+
+    // Track screen exit on unmount with current screenName captured in closure
+    const currentScreen = screenName;
+    return () => {
+      const duration = Date.now() - screenStartTime;
+      trackScreenExit(currentScreen, duration);
+    };
+  }, [screenName, screenStartTime]);
+};