@umituz/react-native-firebase 1.7.0 → 1.7.3

package/src/analytics/infrastructure/services/analytics-initializer.service.ts

@@ -0,0 +1,162 @@
+/**
+ * Analytics Initializer Service
+ * Single Responsibility: Handle analytics initialization logic
+ */
+
+import { Platform } from 'react-native';
+import { getFirebaseApp } from '../../../infrastructure/config/FirebaseClient';
+import { webAnalyticsAdapter } from '../adapters/web-analytics.adapter';
+import { nativeAnalyticsAdapter } from '../adapters/native-analytics.adapter';
+
+export interface AnalyticsInstance {
+  instance: any;
+  platform: 'web' | 'native';
+}
+
+export class AnalyticsInitializerService {
+  private static nativeWarningLogged = false;
+
+  /**
+   * Initialize analytics instance
+   * Returns null if initialization fails
+   */
+  async initialize(): Promise<AnalyticsInstance | null> {
+    // Platform-specific initialization
+    // iOS/Android: Only use native
+    // Web: Only use web
+    if (Platform.OS === 'web') {
+      if (webAnalyticsAdapter) {
+        return this.initializeWeb();
+      }
+      return null;
+    }
+
+    // iOS/Android: Try native only
+    if (nativeAnalyticsAdapter) {
+      return this.initializeNative();
+    }
+
+    // Native not available on iOS/Android - return null
+    // Only log warning once
+    if (__DEV__ && !AnalyticsInitializerService.nativeWarningLogged) {
+      AnalyticsInitializerService.nativeWarningLogged = true;
+      /* eslint-disable-next-line no-console */
+      console.warn(
+        '⚠️ Firebase Analytics: Native module not available on iOS/Android (Expo Go limitation)',
+      );
+    }
+    return null;
+  }
+
+  private async initializeNative(): Promise<AnalyticsInstance | null> {
+    try {
+      if (!nativeAnalyticsAdapter) {
+        /* eslint-disable-next-line no-console */
+        if (__DEV__) {
+          console.warn(
+            '⚠️ Firebase Analytics: Native adapter not available - ensure @react-native-firebase/app and @react-native-firebase/analytics are installed',
+          );
+        }
+        return null;
+      }
+
+      // Try to get Firebase App instance to check if it's initialized
+      let firebaseApp: any = null;
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const firebaseAppModule = require('@react-native-firebase/app');
+        firebaseApp = firebaseAppModule.app();
+      } catch (appError: any) {
+        /* eslint-disable-next-line no-console */
+        if (__DEV__) {
+          const errorMessage = appError?.message || String(appError);
+          if (errorMessage.includes('No Firebase App') || errorMessage.includes('has been created')) {
+            console.warn(
+              '⚠️ Firebase Analytics: Firebase App not initialized. Please add GoogleService-Info.plist to ios/ directory and rebuild the app.',
+            );
+          } else {
+            console.warn('⚠️ Firebase Analytics: Firebase App check failed', appError);
+          }
+        }
+        return null;
+      }
+
+      const instance = nativeAnalyticsAdapter.getAnalytics();
+      if (!instance) {
+        /* eslint-disable-next-line no-console */
+        if (__DEV__) {
+          console.warn('⚠️ Firebase Analytics: getAnalytics() returned null');
+        }
+        return null;
+      }
+
+      /* eslint-disable-next-line no-console */
+      if (__DEV__) {
+        console.log('✅ Firebase Analytics initialized (native)');
+      }
+      return { instance, platform: 'native' };
+    } catch (error: any) {
+      /* eslint-disable-next-line no-console */
+      if (__DEV__) {
+        const errorMessage = error?.message || String(error);
+        if (errorMessage.includes('No Firebase App') || errorMessage.includes('has been created')) {
+          console.warn(
+            '⚠️ Firebase Analytics: Firebase App not initialized. Please add GoogleService-Info.plist to ios/ directory and rebuild the app.',
+          );
+        } else {
+          console.warn('⚠️ Firebase Analytics: Native initialization failed', error);
+        }
+      }
+      return null;
+    }
+  }
+
+  private async initializeWeb(): Promise<AnalyticsInstance | null> {
+    try {
+      // Check if Analytics is supported
+      if (webAnalyticsAdapter) {
+        const isSupported = await webAnalyticsAdapter.isSupported();
+        if (!isSupported) {
+          /* eslint-disable-next-line no-console */
+          if (__DEV__) {
+            console.warn('⚠️ Firebase Analytics: Not supported in this environment (web)');
+          }
+          return null;
+        }
+      }
+
+      const app = getFirebaseApp();
+      if (!app) {
+        /* eslint-disable-next-line no-console */
+        if (__DEV__) {
+          console.warn('⚠️ Firebase Analytics: Firebase app not available');
+        }
+        return null;
+      }
+
+      try {
+        const instance = webAnalyticsAdapter!.getAnalytics(app);
+        /* eslint-disable-next-line no-console */
+        if (__DEV__) {
+          console.log('✅ Firebase Analytics initialized (web)');
+        }
+        return { instance, platform: 'web' };
+      } catch (analyticsError) {
+        /* eslint-disable-next-line no-console */
+        if (__DEV__) {
+          console.warn('⚠️ Firebase Analytics: getAnalytics failed', analyticsError);
+        }
+        return null;
+      }
+    } catch (error) {
+      /* eslint-disable-next-line no-console */
+      if (__DEV__) {
+        console.warn('⚠️ Firebase Analytics: Web initialization failed', error);
+      }
+      return null;
+    }
+  }
+}
+
+export const analyticsInitializerService = new AnalyticsInitializerService();
+

package/src/analytics/infrastructure/services/analytics-user.service.ts

@@ -0,0 +1,98 @@
+/**
+ * Analytics User Service
+ * Single Responsibility: Handle user-related analytics operations
+ */
+
+import { webAnalyticsAdapter } from '../adapters/web-analytics.adapter';
+import { nativeAnalyticsAdapter } from '../adapters/native-analytics.adapter';
+import type { AnalyticsInstance } from './analytics-initializer.service';
+
+export class AnalyticsUserService {
+  /**
+   * Set user ID
+   */
+  async setUserId(
+    analyticsInstance: AnalyticsInstance | null,
+    userId: string,
+  ): Promise<void> {
+    if (!analyticsInstance) {
+      return;
+    }
+
+    try {
+      if (analyticsInstance.platform === 'native' && nativeAnalyticsAdapter) {
+        await nativeAnalyticsAdapter.setUserId(analyticsInstance.instance, userId);
+      } else if (analyticsInstance.platform === 'web' && webAnalyticsAdapter) {
+        await webAnalyticsAdapter.setUserId(analyticsInstance.instance, userId);
+      }
+    } catch (_error) {
+      // Silent fail
+    }
+  }
+
+  /**
+   * Set user property
+   */
+  async setUserProperty(
+    analyticsInstance: AnalyticsInstance | null,
+    key: string,
+    value: string,
+  ): Promise<void> {
+    if (!analyticsInstance) {
+      return;
+    }
+
+    try {
+      if (analyticsInstance.platform === 'native' && nativeAnalyticsAdapter) {
+        await nativeAnalyticsAdapter.setUserProperties(analyticsInstance.instance, {
+          [key]: value,
+        });
+      } else if (analyticsInstance.platform === 'web' && webAnalyticsAdapter) {
+        await webAnalyticsAdapter.setUserProperties(analyticsInstance.instance, {
+          [key]: value,
+        });
+      }
+    } catch (_error) {
+      // Silent fail
+    }
+  }
+
+  /**
+   * Set multiple user properties
+   */
+  async setUserProperties(
+    analyticsInstance: AnalyticsInstance | null,
+    properties: Record<string, string>,
+  ): Promise<void> {
+    for (const [key, value] of Object.entries(properties)) {
+      await this.setUserProperty(analyticsInstance, key, value);
+    }
+  }
+
+  /**
+   * Clear user data
+   */
+  async clearUserData(analyticsInstance: AnalyticsInstance | null): Promise<void> {
+    if (!analyticsInstance) {
+      return;
+    }
+
+    try {
+      if (analyticsInstance.platform === 'native' && nativeAnalyticsAdapter) {
+        await nativeAnalyticsAdapter.setUserId(analyticsInstance.instance, '');
+        await nativeAnalyticsAdapter.setUserProperties(analyticsInstance.instance, {});
+        if (nativeAnalyticsAdapter.resetAnalyticsData) {
+          await nativeAnalyticsAdapter.resetAnalyticsData(analyticsInstance.instance);
+        }
+      } else if (analyticsInstance.platform === 'web' && webAnalyticsAdapter) {
+        await webAnalyticsAdapter.setUserId(analyticsInstance.instance, '');
+        await webAnalyticsAdapter.setUserProperties(analyticsInstance.instance, {});
+      }
+    } catch (_error) {
+      // Silent fail
+    }
+  }
+}
+
+export const analyticsUserService = new AnalyticsUserService();
+

package/src/analytics/infrastructure/services/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Analytics Infrastructure Services
+ * Public API exports
+ */
+
+export { firebaseAnalyticsService } from './FirebaseAnalyticsService';
+export type { IAnalyticsService } from './FirebaseAnalyticsService';
+export { analyticsInitializerService } from './analytics-initializer.service';
+export type { AnalyticsInstance } from './analytics-initializer.service';
+export { analyticsEventService } from './analytics-event.service';
+export { analyticsUserService } from './analytics-user.service';
+

package/src/analytics/presentation/decorators/PerformanceDecorator.ts

@@ -0,0 +1,72 @@
+/**
+ * Performance Decorator
+ *
+ * DDD Pattern: Decorator for automatic performance tracking
+ */
+
+import { performanceTracker } from '../../infrastructure/services/PerformanceTracker';
+
+export function TrackPerformance(operationName?: string) {
+  return function (
+    target: any,
+    propertyKey: string,
+    descriptor: PropertyDescriptor
+  ) {
+    const originalMethod = descriptor.value;
+    const operation = operationName || `${target?.constructor?.name || 'Unknown'}.${propertyKey}`;
+
+    descriptor.value = async function (...args: unknown[]) {
+      const trackingId = `${operation}_${Date.now()}`;
+      return await performanceTracker.track(trackingId, async () => {
+        return await originalMethod.apply(this, args);
+      });
+    };
+
+    return descriptor;
+  };
+}
+
+export function TrackOperation(
+  operationName: string,
+  errorType: 'database' | 'network' | 'auth' | 'cache' | 'generic' = 'generic'
+) {
+  return function (
+    _target: unknown,
+    propertyKey: string,
+    descriptor: PropertyDescriptor
+  ) {
+    const originalMethod = descriptor.value;
+
+    descriptor.value = async function (...args: unknown[]) {
+      const trackingId = `${operationName}_${Date.now()}`;
+      const startTime = Date.now();
+
+      try {
+        performanceTracker.start(trackingId);
+        const result = await originalMethod.apply(this, args);
+
+        await performanceTracker.end(trackingId, {
+          operation: operationName,
+          method: propertyKey,
+          success: true,
+        });
+
+        return result;
+      } catch (error) {
+        await performanceTracker.end(trackingId, {
+          operation: operationName,
+          method: propertyKey,
+          success: false,
+          duration_ms: Date.now() - startTime,
+        });
+
+
+
+        throw error;
+      }
+    };
+
+    return descriptor;
+  };
+}
+

package/src/analytics/presentation/decorators/TrackingDecorator.ts

@@ -0,0 +1,38 @@
+/**
+ * Tracking Decorator
+ * 
+ * DDD Pattern: Decorator for automatic event tracking
+ */
+
+import { firebaseAnalyticsService } from '../../infrastructure/services/FirebaseAnalyticsService';
+
+/**
+ * Decorator to automatically log an event when a method is called
+ */
+export function TrackEvent(eventName: string, params?: Record<string, any>) {
+    return function (
+        _target: any,
+        _propertyKey: string,
+        descriptor: PropertyDescriptor
+    ) {
+        const originalMethod = descriptor.value;
+
+        descriptor.value = async function (...args: any[]) {
+            try {
+                await firebaseAnalyticsService.logEvent(eventName, params);
+            } catch (error) {
+                // Fail silently to not disrupt app flow
+            }
+            return originalMethod.apply(this, args);
+        };
+
+        return descriptor;
+    };
+}
+
+/**
+ * Functional utility to track an event
+ */
+export async function trackEvent(eventName: string, params?: Record<string, any>): Promise<void> {
+    await firebaseAnalyticsService.logEvent(eventName, params);
+}

package/src/analytics/presentation/hooks/useNavigationTracking.ts

@@ -0,0 +1,70 @@
+/**
+ * useNavigationTracking Hook
+ *
+ * Tracks navigation between screens for user journey analysis.
+ * Logs navigation events when user navigates from one screen to another.
+ *
+ * Platform-agnostic: Works on Web, iOS, and Android
+ *
+ * @example
+ * ```typescript
+ * import { useNavigationTracking } from '@umituz/react-native-firebase-analytics';
+ *
+ * function MyScreen() {
+ *   useNavigationTracking('home', 'HomeScreen');
+ *   // ... rest of component
+ * }
+ * ```
+ */
+
+import { useRef, useCallback } from "react";
+import { useFocusEffect } from "@react-navigation/native";
+import { firebaseAnalyticsService } from "../../infrastructure/services/FirebaseAnalyticsService";
+
+/**
+ * Track navigation between screens
+ * @param screenName - Current screen name (e.g., 'home', 'decks', 'settings')
+ * @param screenClass - Current screen class name (e.g., 'HomeScreen', 'DecksScreen')
+ */
+export function useNavigationTracking(
+  screenName: string,
+  screenClass?: string,
+): void {
+  const previousScreenRef = useRef<string | null>(null);
+  const isFirstFocusRef = useRef(true);
+
+  useFocusEffect(
+    useCallback(() => {
+      // Skip first focus (app start)
+      if (isFirstFocusRef.current) {
+        isFirstFocusRef.current = false;
+        previousScreenRef.current = screenName;
+        return;
+      }
+
+      // Log navigation if coming from another screen
+      if (previousScreenRef.current && previousScreenRef.current !== screenName) {
+        /* eslint-disable-next-line no-console */
+        if (__DEV__) {
+          console.log("📊 Navigation tracked:", {
+            from: previousScreenRef.current,
+            to: screenName,
+          });
+        }
+
+        firebaseAnalyticsService
+          .logNavigation({
+            from_screen: previousScreenRef.current,
+            to_screen: screenName,
+            screen_class: screenClass || screenName,
+          })
+          .catch(() => {
+            // Silent fail - analytics is non-critical
+          });
+      }
+
+      previousScreenRef.current = screenName;
+    }, [screenName, screenClass]),
+  );
+}
+

package/src/analytics/presentation/hooks/useScreenTime.ts

@@ -0,0 +1,69 @@
+/**
+ * useScreenTime Hook
+ *
+ * Tracks how long users spend on each screen.
+ * Automatically logs screen_time event when screen is unfocused.
+ *
+ * Platform-agnostic: Works on Web, iOS, and Android
+ *
+ * @example
+ * ```typescript
+ * import { useScreenTime } from '@umituz/react-native-firebase-analytics';
+ *
+ * function MyScreen() {
+ *   useScreenTime('home', 'HomeScreen');
+ *   // ... rest of component
+ * }
+ * ```
+ */
+
+import { useRef, useCallback } from "react";
+import { useFocusEffect } from "@react-navigation/native";
+import { firebaseAnalyticsService } from "../../infrastructure/services/FirebaseAnalyticsService";
+
+/**
+ * Track screen time when screen is focused/unfocused
+ * @param screenName - Screen name (e.g., 'home', 'decks', 'settings')
+ * @param screenClass - Screen class name (e.g., 'HomeScreen', 'DecksScreen')
+ */
+export function useScreenTime(screenName: string, screenClass?: string): void {
+  const startTimeRef = useRef<number | null>(null);
+
+  useFocusEffect(
+    useCallback(() => {
+      // Record start time when screen is focused
+      startTimeRef.current = Date.now();
+
+      return () => {
+        // Calculate time spent when screen is unfocused
+        if (startTimeRef.current !== null) {
+          const timeSpent = Math.round((Date.now() - startTimeRef.current) / 1000); // seconds
+
+          // Only log if user spent at least 1 second on screen
+          if (timeSpent >= 1) {
+            /* eslint-disable-next-line no-console */
+            if (__DEV__) {
+              console.log("📊 Screen time tracked:", {
+                screen: screenName,
+                timeSpent: `${timeSpent}s`,
+              });
+            }
+
+            firebaseAnalyticsService
+              .logScreenTime({
+                screen_name: screenName,
+                screen_class: screenClass || screenName,
+                time_spent_seconds: timeSpent,
+              })
+              .catch(() => {
+                // Silent fail - analytics is non-critical
+              });
+          }
+
+          startTimeRef.current = null;
+        }
+      };
+    }, [screenName, screenClass]),
+  );
+}
+

package/src/analytics/presentation/hooks/useScreenView.ts

@@ -0,0 +1,70 @@
+/**
+ * useScreenView Hook
+ *
+ * Comprehensive screen tracking hook that combines:
+ * - Screen view tracking (when screen is focused)
+ * - Screen time tracking (how long user stays on screen)
+ * - Navigation tracking (from/to screen transitions)
+ *
+ * Platform-agnostic: Works on Web, iOS, and Android
+ *
+ * @example
+ * ```typescript
+ * import { useScreenView } from '@umituz/react-native-firebase-analytics';
+ *
+ * function MyScreen() {
+ *   useScreenView('home', 'HomeScreen');
+ *   // ... rest of component
+ * }
+ * ```
+ */
+
+import { useCallback } from "react";
+import { useFocusEffect } from "@react-navigation/native";
+import { InteractionManager } from "react-native";
+import { firebaseAnalyticsService } from "../../infrastructure/services/FirebaseAnalyticsService";
+import { useScreenTime } from "./useScreenTime";
+import { useNavigationTracking } from "./useNavigationTracking";
+
+/**
+ * Track screen view, time, and navigation when screen is focused
+ * @param screenName - Screen name (e.g., 'home', 'decks', 'settings')
+ * @param screenClass - Screen class name (e.g., 'HomeScreen', 'DecksScreen')
+ */
+export function useScreenView(screenName: string, screenClass?: string): void {
+  // Track screen time (how long user stays on screen)
+  useScreenTime(screenName, screenClass);
+
+  // Track navigation (from/to screen transitions)
+  useNavigationTracking(screenName, screenClass);
+
+  // Track screen view (when screen is focused)
+  useFocusEffect(
+    useCallback(() => {
+      // Defer analytics until screen transition animation completes
+      const task = InteractionManager.runAfterInteractions(() => {
+        /* eslint-disable-next-line no-console */
+        if (__DEV__) {
+          console.log("📊 Screen view tracked:", {
+            screen: screenName,
+            screenClass: screenClass || screenName,
+          });
+        }
+
+        firebaseAnalyticsService
+          .logScreenView({
+            screen_name: screenName,
+            screen_class: screenClass || screenName,
+          })
+          .catch(() => {
+            // Silent fail - analytics is non-critical
+          });
+      });
+
+      return () => {
+        task.cancel();
+      };
+    }, [screenName, screenClass]),
+  );
+}
+

package/src/analytics/presentation/utils/analyticsUtils.ts

@@ -0,0 +1,78 @@
+/**
+ * Analytics Utilities
+ *
+ * Helper functions for tracking user interactions and events.
+ * Platform-agnostic: Works on Web, iOS, and Android
+ */
+
+import { firebaseAnalyticsService } from "../../infrastructure/services/FirebaseAnalyticsService";
+
+/**
+ * Track button click
+ * @param buttonId - Unique button identifier (e.g., 'create_deck', 'delete_card')
+ * @param options - Optional parameters
+ */
+export function trackButtonClick(
+  buttonId: string,
+  options?: {
+    buttonName?: string;
+    screenName?: string;
+    screenClass?: string;
+    [key: string]: string | number | boolean | null | undefined;
+  },
+): void {
+  const { buttonName, screenName, screenClass, ...additionalParams } =
+    options || {};
+
+  const params = {
+    button_id: buttonId,
+    button_name: buttonName || buttonId,
+    screen_name: screenName || "unknown",
+    screen_class: screenClass || screenName || "unknown",
+    ...additionalParams,
+  };
+
+  /* eslint-disable-next-line no-console */
+  if (__DEV__) {
+    console.log("📊 Button click tracked:", {
+      buttonId,
+      buttonName: buttonName || buttonId,
+      screenName: screenName || "unknown",
+      ...additionalParams,
+    });
+  }
+
+  firebaseAnalyticsService
+    .logButtonClick(params)
+    .catch(() => {
+      // Silent fail - analytics is non-critical
+    });
+}
+
+/**
+ * Track CRUD operation
+ * @param operation - Operation type ('create', 'update', 'delete', 'read')
+ * @param entityType - Entity type ('deck', 'card', 'category', etc.)
+ * @param entityId - Entity ID
+ * @param additionalParams - Additional parameters to track
+ */
+export function trackCRUDOperation(
+  operation: "create" | "update" | "delete" | "read",
+  entityType: string,
+  entityId: string,
+  additionalParams?: Record<string, string | number | boolean | null>,
+): void {
+  const eventName = `${entityType}_${operation}d`;
+
+  firebaseAnalyticsService
+    .logEvent(eventName, {
+      [`${entityType}_id`]: entityId,
+      operation,
+      entity_type: entityType,
+      ...additionalParams,
+    })
+    .catch(() => {
+      // Silent fail - analytics is non-critical
+    });
+}
+

package/src/crashlytics/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Firebase Crashlytics Module
+ */
+
+export { firebaseCrashlyticsService } from './infrastructure/services/FirebaseCrashlyticsService';
+export type { ICrashlyticsService } from './infrastructure/services/FirebaseCrashlyticsService';
+export { crashlyticsInitializerService } from './infrastructure/services/crashlytics-initializer.service';
+export { crashlyticsErrorService } from './infrastructure/services/crashlytics-error.service';
+export { crashlyticsUserService } from './infrastructure/services/crashlytics-user.service';

package/src/crashlytics/infrastructure/adapters/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Crashlytics Adapters
+ * Platform-specific implementations
+ */
+
+export { nativeCrashlyticsAdapter } from './native-crashlytics.adapter';
+export type { NativeCrashlyticsAdapter } from './native-crashlytics.adapter';
+