@trustchex/react-native-sdk 1.253.0 → 1.266.0

package/src/Shared/Services/AnalyticsService.ts

@@ -0,0 +1,470 @@
+/**
+ * Analytics Service - GDPR/KVKK/PCI-DSS Compliant
+ * Sends events immediately when they occur, sanitizes PII
+ */
+
+import { AppState, type AppStateStatus } from 'react-native';
+import DeviceInfo from 'react-native-device-info';
+import RNFS from 'react-native-fs';
+import 'react-native-get-random-values';
+import { v4 as uuidv4 } from 'uuid';
+import packageJson from '../../../package.json';
+import {
+  AnalyticsEventCategory,
+  AnalyticsEventName,
+} from '../Types/analytics.types';
+import type {
+  AnalyticsConfig,
+  AnalyticsEvent,
+  AnalyticsEventMetadata,
+  AnonymizedDeviceInfo,
+  IAnalyticsService,
+} from '../Types/analytics.types';
+
+class AnalyticsService implements IAnalyticsService {
+  private config: AnalyticsConfig | null = null;
+  private sessionId: string | null = null;
+  private deviceInfo: AnonymizedDeviceInfo | null = null;
+  private isDemoSession: boolean = false;
+
+  // Batching configuration
+  private queue: AnalyticsEvent[] = [];
+  private readonly BATCH_SIZE = 10;
+  private readonly MAX_QUEUE_SIZE = 100; // Prevent memory issues
+  private readonly FLUSH_INTERVAL = 5000; // 5 seconds
+  private readonly QUEUE_FILE_PATH = `${RNFS.CachesDirectoryPath}/trustchex_analytics_queue.json`;
+  private flushTimer: ReturnType<typeof setInterval> | null = null;
+  private isFlushing = false;
+  private appStateSubscription: { remove: () => void } | null = null;
+
+  // Critical events that should flush immediately
+  private readonly CRITICAL_EVENTS = [
+    AnalyticsEventName.SESSION_END,
+    AnalyticsEventName.VERIFICATION_SUCCESS,
+    AnalyticsEventName.VERIFICATION_FAILED,
+  ];
+
+  /**
+   * Set demo session flag to disable analytics for demo sessions
+   */
+  setDemoSession(isDemoSession: boolean): void {
+    this.isDemoSession = isDemoSession;
+  }
+
+  /**
+   * Initialize the analytics service
+   * @param config Analytics configuration with required verification sessionId
+   */
+  async initialize(config: AnalyticsConfig): Promise<void> {
+    // Prevent double initialization
+    if (this.config) {
+      return;
+    }
+
+    // Validate required verificationSessionId
+    if (!config.verificationSessionId) {
+      throw new Error('Analytics initialization failed: verificationSessionId is required (must be verification session ID from backend)');
+    }
+
+    // Merge with defaults
+    this.config = {
+      enabled: config.enabled ?? true,
+      baseUrl: config.baseUrl,
+      verificationSessionId: config.verificationSessionId,
+    };
+
+    this.sessionId = config.verificationSessionId;
+
+    // Load persisted queue
+    await this.loadPersistedQueue();
+
+    // Collect anonymized device information
+    await this.collectDeviceInfo();
+
+    // Start flush timer
+    this.startFlushTimer();
+
+    // Listen for app state changes to flush before backgrounding
+    this.appStateSubscription = AppState.addEventListener(
+      'change',
+      this.handleAppStateChange.bind(this)
+    );
+  }
+
+  /**
+   * Handle app state changes - flush when going to background
+   */
+  private handleAppStateChange(nextAppState: AppStateStatus): void {
+    if (nextAppState === 'background' || nextAppState === 'inactive') {
+      // Persist queue first to ensure data safety, then flush
+      // Note: We don't await here as AppState callbacks are sync,
+      // but the operations are queued and will complete
+      this.persistQueue().then(() => this.flush());
+    }
+  }
+
+  /**
+   * Load persisted queue from disk
+   */
+  private async loadPersistedQueue(): Promise<void> {
+    try {
+      if (await RNFS.exists(this.QUEUE_FILE_PATH)) {
+        const content = await RNFS.readFile(this.QUEUE_FILE_PATH, 'utf8');
+        const persistedQueue = JSON.parse(content);
+        if (Array.isArray(persistedQueue) && persistedQueue.length > 0) {
+          // Merge with existing queue, prioritizing persisted events
+          this.queue = [...persistedQueue, ...this.queue];
+          if (__DEV__) console.log(`[Analytics] Loaded ${persistedQueue.length} events from disk`);
+        }
+        // Clear the file after loading to prevent duplicate loads
+        await RNFS.unlink(this.QUEUE_FILE_PATH);
+      }
+    } catch (error) {
+      if (__DEV__) console.warn('[Analytics] Failed to load persisted queue:', error);
+    }
+  }
+
+  /**
+   * Persist queue to disk
+   */
+  private async persistQueue(): Promise<void> {
+    try {
+      if (this.queue.length === 0) {
+        if (await RNFS.exists(this.QUEUE_FILE_PATH)) {
+          await RNFS.unlink(this.QUEUE_FILE_PATH);
+        }
+        return;
+      }
+      await RNFS.writeFile(this.QUEUE_FILE_PATH, JSON.stringify(this.queue), 'utf8');
+    } catch (error) {
+      if (__DEV__) console.warn('[Analytics] Failed to persist queue:', error);
+    }
+  }
+
+  /**
+   * Track an analytics event - adds to queue and flushes if full
+   */
+  async trackEvent(
+    eventName: string,
+    category: AnalyticsEventCategory,
+    metadata?: AnalyticsEventMetadata
+  ): Promise<void> {
+    // Skip analytics for demo sessions
+    if (this.isDemoSession) {
+      return;
+    }
+
+    // Skip if not initialized or disabled
+    if (!this.config?.enabled || !this.sessionId) {
+      return;
+    }
+
+    // Collect device info on first event if not already done
+    if (!this.deviceInfo) {
+      await this.collectDeviceInfo();
+    }
+
+    // Sanitize metadata to remove any potential PII
+    const sanitizedMetadata = this.sanitizeMetadata({
+      ...metadata,
+      deviceModel: DeviceInfo.getModel(),
+    });
+
+    const event: AnalyticsEvent = {
+      eventId: uuidv4(),
+      verificationSessionId: this.sessionId,
+      eventName,
+      category,
+      timestamp: new Date().toISOString(),
+      deviceInfo: this.deviceInfo!,
+      metadata: sanitizedMetadata,
+    };
+
+    // Check if this is a critical event that should flush immediately
+    const isCriticalEvent = this.CRITICAL_EVENTS.includes(
+      eventName as AnalyticsEventName
+    );
+
+    // Add to queue
+    this.queue.push(event);
+
+    // Drop oldest events if queue exceeds max size (prevent memory issues)
+    if (this.queue.length > this.MAX_QUEUE_SIZE) {
+      const dropped = this.queue.length - this.MAX_QUEUE_SIZE;
+      this.queue = this.queue.slice(dropped);
+      if (__DEV__) console.warn(`[Analytics] Queue overflow, dropped ${dropped} oldest events`);
+    }
+
+    // Flush immediately for critical events or if batch size reached
+    if (isCriticalEvent || this.queue.length >= this.BATCH_SIZE) {
+      await this.flush();
+    }
+  }
+
+  /**
+   * Start the periodic flush timer
+   */
+  private startFlushTimer(): void {
+    if (this.flushTimer) return;
+
+    this.flushTimer = setInterval(() => {
+      this.flush();
+    }, this.FLUSH_INTERVAL);
+  }
+
+  /**
+   * Stop the flush timer
+   */
+  private stopFlushTimer(): void {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+
+  /**
+   * Flush the event queue
+   */
+  async flush(): Promise<void> {
+    // Early return checks - must be atomic with setting isFlushing
+    if (this.queue.length === 0 || this.isFlushing || !this.config) {
+      return;
+    }
+
+    // Set flag immediately to prevent race conditions
+    this.isFlushing = true;
+
+    // Take a batch, but don't remove from queue yet until success
+    const batchSize = Math.min(this.queue.length, this.BATCH_SIZE);
+    const batch = this.queue.slice(0, batchSize);
+    
+    // Double-check batch has items (defensive programming)
+    if (batch.length === 0) {
+      this.isFlushing = false;
+      return;
+    }
+
+    try {
+      await this.sendBatchWithRetry(batch);
+      
+      // Remove sent events
+      this.queue = this.queue.slice(batchSize);
+      
+      // Update persistence
+      await this.persistQueue();
+    } catch (error) {
+      // On failure, we keep events in the queue
+      if (__DEV__) console.warn('[Analytics] Failed to flush batch, keeping events:', error);
+      
+      // Ensure they are persisted
+      await this.persistQueue();
+    } finally {
+      this.isFlushing = false;
+    }
+  }
+
+  /**
+   * Send batch with retry logic (exponential backoff: 1s, 2s, 4s)
+   */
+  private async sendBatchWithRetry(events: AnalyticsEvent[], maxRetries = 3, attempt = 1): Promise<void> {
+    if (!this.config || events.length === 0) return;
+
+    try {
+      const response = await fetch(
+        `${this.config.baseUrl}/api/app/mobile/analytics`,
+        {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify(events),
+        }
+      );
+
+      if (!response.ok) {
+        if (attempt <= maxRetries && response.status >= 500) {
+          // Retry on server errors with exponential backoff
+          const delay = Math.pow(2, attempt - 1) * 1000; // 1s, 2s, 4s
+          await new Promise(resolve => setTimeout(resolve, delay));
+          return this.sendBatchWithRetry(events, maxRetries, attempt + 1);
+        }
+        // For 429 (Too Many Requests), throw to retry
+        if (response.status === 429) {
+          throw new Error('Rate limit exceeded');
+        }
+        
+        // For other 4xx errors (Bad Request, Unauthorized, etc.), do NOT retry.
+        // We return successfully so the bad events are removed from the queue.
+        if (response.status >= 400 && response.status < 500) {
+          if (__DEV__) console.warn(`[Analytics] Dropping batch due to ${response.status} error`);
+          return;
+        }
+        
+        if (__DEV__) console.warn('[Analytics] Failed to send batch:', response.status);
+      }
+    } catch (error) {
+      if (attempt <= maxRetries) {
+        // Retry on network errors with exponential backoff
+        const delay = Math.pow(2, attempt - 1) * 1000;
+        await new Promise(resolve => setTimeout(resolve, delay));
+        return this.sendBatchWithRetry(events, maxRetries, attempt + 1);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Clear analytics session and reset all state
+   */
+  async clear(): Promise<void> {
+    // Flush any pending events before clearing
+    await this.flush();
+    
+    this.stopFlushTimer();
+    
+    // Remove AppState listener
+    if (this.appStateSubscription) {
+      this.appStateSubscription.remove();
+      this.appStateSubscription = null;
+    }
+    
+    this.queue = [];
+    this.sessionId = null;
+    this.deviceInfo = null;
+    this.config = null;
+  }
+
+  /**
+   * Check if analytics is enabled
+   */
+  isEnabled(): boolean {
+    return this.config?.enabled === true && this.sessionId !== null;
+  }
+
+  /**
+   * Private: Collect anonymized device information
+   */
+  private async collectDeviceInfo(): Promise<void> {
+    try {
+      const platform = DeviceInfo.getSystemName().toLowerCase();
+
+      this.deviceInfo = {
+        platform: platform as 'ios' | 'android',
+        osVersion: DeviceInfo.getSystemVersion(),
+        appVersion: DeviceInfo.getVersion(),
+        sdkVersion: packageJson.version,
+        locale: 'en', // Will be set from app context
+        timezone: new Date().toTimeString().split(' ')[1] || 'UTC',
+        screenResolution: `${DeviceInfo.getDeviceType()}`,
+      };
+    } catch (error) {
+      if (__DEV__) console.warn('[Analytics] Error collecting device info:', error);
+      // Fallback device info
+      this.deviceInfo = {
+        platform: 'android',
+        osVersion: 'unknown',
+        appVersion: 'unknown',
+        sdkVersion: packageJson.version,
+        locale: 'en',
+        timezone: 'UTC',
+        screenResolution: 'unknown',
+      };
+    }
+  }
+
+  /**
+   * Update device locale from app context
+   */
+  public setLocale(locale: string): void {
+    if (this.deviceInfo) {
+      this.deviceInfo.locale = locale;
+    }
+  }
+
+  /**
+   * Private: Sanitize metadata to remove PII
+   */
+  private sanitizeMetadata(
+    metadata?: AnalyticsEventMetadata
+  ): AnalyticsEventMetadata | undefined {
+    if (!metadata) return undefined;
+
+    const sanitized: AnalyticsEventMetadata = {};
+    const forbiddenKeys = [
+      'email',
+      'emailaddress',
+      'phone',
+      'phonenumber',
+      'firstname',
+      'lastname',
+      'fullname',
+      'address',
+      'streetaddress',
+      'ssn',
+      'socialsecurity',
+      'passport',
+      'passportnumber',
+      'driverlicense',
+      'creditcard',
+      'cardnumber',
+      'cvv',
+      'password',
+      'apikey',
+      'accesstoken',
+    ];
+
+    for (const [key, value] of Object.entries(metadata)) {
+      const lowerKey = key.toLowerCase();
+
+      // Skip if key is exactly a forbidden key or contains it as a word boundary
+      // But allow compound words like "buttonName", "screenName"
+      const isForbidden = forbiddenKeys.some((forbidden) => {
+        // Check for exact match
+        if (lowerKey === forbidden) return true;
+
+        // Check if forbidden word appears at start followed by non-letter
+        if (lowerKey.startsWith(forbidden) && lowerKey.length > forbidden.length) {
+          const nextChar = lowerKey[forbidden.length];
+          if (!/[a-z]/.test(nextChar)) return true;
+        }
+
+        // Check if forbidden word appears at end preceded by non-letter
+        if (lowerKey.endsWith(forbidden) && lowerKey.length > forbidden.length) {
+          const prevChar = lowerKey[lowerKey.length - forbidden.length - 1];
+          if (!/[a-z]/.test(prevChar)) return true;
+        }
+
+        return false;
+      });
+
+      if (isForbidden) {
+        continue;
+      }
+
+      // Skip if value looks like email
+      if (
+        typeof value === 'string' &&
+        /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
+      ) {
+        continue;
+      }
+
+      // Skip if value looks like phone number
+      if (typeof value === 'string' && /^\+?[\d\s\-()]{10,}$/.test(value)) {
+        continue;
+      }
+
+      // Skip if value looks like credit card
+      if (typeof value === 'string' && /^\d{13,19}$/.test(value)) {
+        continue;
+      }
+
+      sanitized[key] = value;
+    }
+
+    return sanitized;
+  }
+}
+
+// Singleton instance
+export const analyticsService = new AnalyticsService();

package/src/Shared/Types/analytics.types.ts

@@ -0,0 +1,179 @@
+/**
+ * Analytics Types for Trustchex React Native SDK
+ * GDPR, KVKK, and PCI-DSS Compliant Analytics System
+ */
+
+/**
+ * Categories of analytics events
+ */
+export enum AnalyticsEventCategory {
+  SESSION = 'session',
+  NAVIGATION = 'navigation',
+  USER_ACTION = 'user_action',
+  ERROR = 'error',
+  PERFORMANCE = 'performance',
+  VERIFICATION = 'verification',
+}
+
+/**
+ * Error severity levels for analytics tracking
+ */
+export type ErrorSeverity = 'low' | 'medium' | 'high' | 'critical';
+
+/**
+ * Error categories for grouping similar errors
+ */
+export enum ErrorCategory {
+  NETWORK = 'network',
+  PERMISSION = 'permission',
+  CAMERA = 'camera',
+  NFC = 'nfc',
+  VALIDATION = 'validation',
+  API = 'api',
+  STORAGE = 'storage',
+  DEVICE = 'device',
+  USER_INPUT = 'user_input',
+  SYSTEM = 'system',
+  UNKNOWN = 'unknown',
+}
+
+/**
+ * Context information for error tracking
+ */
+export interface ErrorContext {
+  /** The component or module where the error occurred */
+  component?: string;
+  /** User action that triggered the error */
+  userAction?: string;
+  /** Whether the error is recoverable */
+  recoverable?: boolean;
+  /** Number of retry attempts made */
+  retryCount?: number;
+  /** Sanitized stack trace (no PII) */
+  stackTrace?: string;
+  /** Additional context data */
+  additionalData?: Record<string, string | number | boolean | null>;
+}
+
+/**
+ * Event names for different analytics events
+ */
+export enum AnalyticsEventName {
+  // Session Events
+  SESSION_START = 'session_start',
+  SESSION_END = 'session_end',
+
+  // Navigation Events
+  SCREEN_VIEW = 'screen_view',
+  SCREEN_EXIT = 'screen_exit',
+
+  // User Action Events
+  BUTTON_CLICK = 'button_click',
+  CONSENT_GIVEN = 'consent_given',
+  STEP_SKIPPED = 'step_skipped',
+  STEP_ABANDONED = 'step_abandoned',
+
+  // Workflow Step Events (started/completed)
+  CONTRACT_ACCEPTANCE_STARTED = 'contract_acceptance_started',
+  CONTRACT_ACCEPTANCE_COMPLETED = 'contract_acceptance_completed',
+  DOCUMENT_SCAN_STARTED = 'identity_document_scan_started',
+  DOCUMENT_SCAN_COMPLETED = 'identity_document_scan_completed',
+  IDENTITY_DOCUMENT_EID_SCAN_STARTED = 'identity_document_eid_scan_started',
+  IDENTITY_DOCUMENT_EID_SCAN_COMPLETED = 'identity_document_eid_scan_completed',
+  LIVENESS_CHECK_STARTED = 'liveness_check_started',
+  LIVENESS_CHECK_COMPLETED = 'liveness_check_completed',
+
+  // NFC Scan Events (used by trackNFCScan* helpers)
+  NFC_SCAN_STARTED = 'nfc_scan_started',
+  NFC_SCAN_COMPLETED = 'nfc_scan_completed',
+
+  // NFC Error Events (specific error types for NFC failures)
+  NFC_SCAN_FAILED = 'nfc_scan_failed',
+  NFC_DEVICE_UNSUPPORTED = 'nfc_device_unsupported',
+  NFC_READING_ERROR = 'nfc_reading_error',
+  NFC_USER_CANCELLED = 'nfc_user_cancelled',
+
+  // EID Error Events
+  IDENTITY_DOCUMENT_EID_SCAN_FAILED = 'identity_document_eid_scan_failed',
+
+  // Performance Events
+  API_CALL_DURATION = 'api_call_duration',
+
+  // Verification Outcome Events
+  VERIFICATION_SUCCESS = 'verification_success',
+  VERIFICATION_FAILED = 'verification_failed',
+}
+
+/**
+ * Device information (anonymized and privacy-compliant)
+ */
+export interface AnonymizedDeviceInfo {
+  platform: 'ios' | 'android';
+  osVersion: string;
+  appVersion: string;
+  sdkVersion: string;
+  locale: string;
+  timezone: string;
+  screenResolution: string;
+  // No device IDs, MAC addresses, or other PII
+}
+
+/**
+ * Analytics event metadata
+ */
+export interface AnalyticsEventMetadata {
+  [key: string]: string | number | boolean | null | undefined;
+}
+
+/**
+ * Base analytics event structure
+ */
+export interface AnalyticsEvent {
+  eventId: string; // UUID v4
+  verificationSessionId: string; // Verification session ID from backend
+  eventName: string;
+  category: AnalyticsEventCategory;
+  timestamp: string; // ISO 8601 format
+  deviceInfo: AnonymizedDeviceInfo;
+  metadata?: AnalyticsEventMetadata;
+  // No PII fields allowed
+}
+
+/**
+ * Analytics configuration
+ */
+export interface AnalyticsConfig {
+  enabled: boolean;
+  baseUrl: string;
+  verificationSessionId: string; // Required: Verification session ID from backend
+}
+
+/**
+ * Analytics service interface
+ */
+export interface IAnalyticsService {
+  initialize(config: AnalyticsConfig): Promise<void>;
+  trackEvent(
+    eventName: string,
+    category: AnalyticsEventCategory,
+    metadata?: AnalyticsEventMetadata
+  ): Promise<void>;
+  clear(): Promise<void>;
+  isEnabled(): boolean;
+}
+
+/**
+ * Enhanced error event metadata
+ */
+export interface ErrorEventMetadata extends AnalyticsEventMetadata {
+  errorCode: string;
+  errorMessage: string;
+  screenName: string;
+  severity: ErrorSeverity;
+  category?: ErrorCategory;
+  component?: string;
+  userAction?: string;
+  recoverable?: boolean;
+  retryCount?: number;
+  stackTrace?: string;
+}

package/src/Shared/VisionCameraPlugins/BarcodeScanner/hooks/useCameraPermissions.ts

@@ -23,6 +23,7 @@ export const useCameraPermissions = (): UseCameraPermissionResult => {
     const permission = await requestCameraPermission();
 
     if (!permission) {
+      // Camera permission denied by user - their choice, not actionable
       Alert.alert(
         'Camera Permission Required',
         'This app needs camera access to scan barcodes. Please enable camera permissions in your device settings.',

package/src/Translation/Resources/tr.ts

@@ -62,7 +62,8 @@ export default {
   'livenessDetectionScreen.guideHeader': 'Yüz Taraması İçin Hazırlanın',
   'livenessDetectionScreen.guideText':
     'Başlamadan önce lütfen aşağıdaki hususlara dikkat edin:',
-  'livenessDetectionScreen.guidePoint1': 'Gözlük, şapka veya eşarp takmayın. Lütfen uygun şekilde giyindiğinizden emin olun',
+  'livenessDetectionScreen.guidePoint1':
+    'Gözlük, şapka veya eşarp takmayın. Lütfen uygun şekilde giyindiğinizden emin olun',
   'livenessDetectionScreen.guidePoint2':
     'Yüzünüzün iyi aydınlatıldığından emin olun',
   'livenessDetectionScreen.guidePoint3': 'Arka plan gürültüsünü minimize edin',

package/src/Translation/index.ts

@@ -2,6 +2,8 @@ import i18n from 'i18next';
 import { initReactI18next } from 'react-i18next';
 import * as resources from './Resources';
 
+import { trackError } from '../Shared/Libs/analytics.utils';
+
 const getCurrentLanguage = () => {
   try {
     if (typeof Intl !== 'undefined' && Intl.DateTimeFormat) {
@@ -15,6 +17,13 @@ const getCurrentLanguage = () => {
     return 'en';
   } catch (error) {
     console.error('Error detecting language:', error);
+    trackError(
+      'LANGUAGE_DETECTION_ERROR',
+      error instanceof Error ? error.message : 'Unknown error',
+      'translation_init',
+      'low',
+      { recoverable: true, userAction: 'detect_language' }
+    ).catch(() => { });
     return 'en';
   }
 };