vibefast-cli 1.1.5 → 1.3.0

package/recipes/onboarding/apps/native/src/features/onboarding/hooks/use-onboarding-analytics.ts

@@ -0,0 +1,323 @@
+import { useCallback, useEffect, useRef } from 'react';
+
+import { usePostHogAnalyticsAdapter } from '@/core/analytics';
+
+import type {
+  OnboardingFlowConfig,
+  OnboardingSession,
+} from '../services/onboarding-analytics';
+import { OnboardingAnalyticsService } from '../services/onboarding-analytics';
+
+/**
+ * Configuration for the onboarding analytics hook
+ */
+export type UseOnboardingAnalyticsConfig = {
+  flowConfig: OnboardingFlowConfig;
+  userType?: 'new' | 'returning' | 'migrated';
+  autoStart?: boolean; // Whether to automatically start tracking when hook is called
+};
+
+/**
+ * Return type for the onboarding analytics hook
+ */
+export type OnboardingAnalyticsActions = {
+  // Flow control
+  startFlow: () => Promise<string>;
+  completeFlow: () => Promise<void>;
+  abandonFlow: (reason?: string) => Promise<void>;
+
+  // Step tracking
+  trackStepViewed: (
+    stepId: string,
+    properties?: Record<string, any>,
+  ) => Promise<void>;
+  trackStepCompleted: (
+    stepId: string,
+    properties?: Record<string, any>,
+  ) => Promise<void>;
+  trackStepSkipped: (
+    stepId: string,
+    reason?: string,
+    properties?: Record<string, any>,
+  ) => Promise<void>;
+  trackStepRetried: (
+    stepId: string,
+    attempt: number,
+    properties?: Record<string, any>,
+  ) => Promise<void>;
+  trackStepHelp: (
+    stepId: string,
+    helpType?: string,
+    properties?: Record<string, any>,
+  ) => Promise<void>;
+
+  // Navigation tracking
+  trackNavigation: (
+    direction: 'back' | 'forward',
+    fromStepId: string,
+    toStepId: string,
+  ) => Promise<void>;
+
+  // State access
+  getCurrentSession: () => OnboardingSession | null;
+  getProgress: () => {
+    totalSteps: number;
+    currentStep: number;
+    completedSteps: number;
+    skippedSteps: number;
+    completionRate: number;
+  } | null;
+
+  // Utilities
+  isStepCompleted: (stepId: string) => boolean;
+  isStepSkipped: (stepId: string) => boolean;
+  getNextStep: (currentStepId: string) => string | null;
+  getPreviousStep: (currentStepId: string) => string | null;
+};
+
+/**
+ * Hook for tracking onboarding analytics with automatic step discovery.
+ * Provides a clean, React-friendly interface for onboarding event tracking.
+ *
+ * @example
+ * ```typescript
+ * const analytics = useOnboardingAnalytics({
+ *   flowConfig: {
+ *     flowId: 'main_onboarding',
+ *     flowName: 'Main App Onboarding',
+ *     steps: [
+ *       { id: 'welcome', name: 'Welcome Screen', index: 0 },
+ *       { id: 'permissions', name: 'Permissions Setup', index: 1 },
+ *       { id: 'profile', name: 'Profile Creation', index: 2, isOptional: true },
+ *     ]
+ *   },
+ *   userType: 'new',
+ *   autoStart: true
+ * });
+ *
+ * // In your component
+ * const handleStepComplete = () => {
+ *   analytics.trackStepCompleted('welcome', { interaction_method: 'button' });
+ * };
+ * ```
+ */
+export function useOnboardingAnalytics(
+  config: UseOnboardingAnalyticsConfig,
+): OnboardingAnalyticsActions {
+  const postHogAdapter = usePostHogAnalyticsAdapter();
+  const analyticsServiceRef = useRef<OnboardingAnalyticsService | null>(null);
+
+  // Initialize analytics service
+  useEffect(() => {
+    let isActive = true;
+    const service = new OnboardingAnalyticsService(postHogAdapter);
+    analyticsServiceRef.current = service;
+
+    const bootstrap = async () => {
+      try {
+        await postHogAdapter.initialize();
+        if (config.autoStart && isActive) {
+          await service.startFlow(config.flowConfig, config.userType);
+        }
+      } catch (error) {
+        console.warn(
+          '[useOnboardingAnalytics] Failed to initialize analytics service',
+          error,
+        );
+      }
+    };
+
+    void bootstrap();
+
+    // Cleanup on unmount - track abandonment if session is active
+    return () => {
+      isActive = false;
+      if (analyticsServiceRef.current?.getCurrentSession()) {
+        analyticsServiceRef.current.trackFlowAbandoned('component_unmount');
+      }
+    };
+  }, [postHogAdapter, config.autoStart, config.userType, config.flowConfig]);
+
+  // Flow control functions
+  const startFlow = useCallback(async (): Promise<string> => {
+    if (!analyticsServiceRef.current) {
+      throw new Error('Analytics service not initialized');
+    }
+    return analyticsServiceRef.current.startFlow(
+      config.flowConfig,
+      config.userType,
+    );
+  }, [config.flowConfig, config.userType]);
+
+  const completeFlow = useCallback(async (): Promise<void> => {
+    if (!analyticsServiceRef.current) return;
+    await analyticsServiceRef.current.trackFlowCompleted();
+  }, []);
+
+  const abandonFlow = useCallback(async (reason?: string): Promise<void> => {
+    if (!analyticsServiceRef.current) return;
+    await analyticsServiceRef.current.trackFlowAbandoned(reason);
+  }, []);
+
+  // Step tracking functions
+  const trackStepViewed = useCallback(
+    async (stepId: string, properties?: Record<string, any>): Promise<void> => {
+      if (!analyticsServiceRef.current) return;
+      await analyticsServiceRef.current.trackStepViewed(stepId, properties);
+    },
+    [],
+  );
+
+  const trackStepCompleted = useCallback(
+    async (stepId: string, properties?: Record<string, any>): Promise<void> => {
+      if (!analyticsServiceRef.current) return;
+      await analyticsServiceRef.current.trackStepCompleted(stepId, properties);
+    },
+    [],
+  );
+
+  const trackStepSkipped = useCallback(
+    async (
+      stepId: string,
+      reason?: string,
+      properties?: Record<string, any>,
+    ): Promise<void> => {
+      if (!analyticsServiceRef.current) return;
+      await analyticsServiceRef.current.trackStepSkipped(
+        stepId,
+        reason,
+        properties,
+      );
+    },
+    [],
+  );
+
+  const trackStepRetried = useCallback(
+    async (
+      stepId: string,
+      attempt: number,
+      properties?: Record<string, any>,
+    ): Promise<void> => {
+      if (!analyticsServiceRef.current) return;
+      await analyticsServiceRef.current.trackStepRetried(
+        stepId,
+        attempt,
+        properties,
+      );
+    },
+    [],
+  );
+
+  const trackStepHelp = useCallback(
+    async (
+      stepId: string,
+      helpType?: string,
+      properties?: Record<string, any>,
+    ): Promise<void> => {
+      if (!analyticsServiceRef.current) return;
+      await analyticsServiceRef.current.trackStepHelpAccessed(
+        stepId,
+        helpType,
+        properties,
+      );
+    },
+    [],
+  );
+
+  // Navigation tracking
+  const trackNavigation = useCallback(
+    async (
+      direction: 'back' | 'forward',
+      fromStepId: string,
+      toStepId: string,
+    ): Promise<void> => {
+      if (!analyticsServiceRef.current) return;
+      await analyticsServiceRef.current.trackNavigation(
+        direction,
+        fromStepId,
+        toStepId,
+      );
+    },
+    [],
+  );
+
+  // State access functions
+  const getCurrentSession = useCallback((): OnboardingSession | null => {
+    return analyticsServiceRef.current?.getCurrentSession() || null;
+  }, []);
+
+  const getProgress = useCallback(() => {
+    return analyticsServiceRef.current?.getFlowProgress() || null;
+  }, []);
+
+  // Utility functions
+  const isStepCompleted = useCallback(
+    (stepId: string): boolean => {
+      const session = getCurrentSession();
+      return session?.completedSteps.includes(stepId) || false;
+    },
+    [getCurrentSession],
+  );
+
+  const isStepSkipped = useCallback(
+    (stepId: string): boolean => {
+      const session = getCurrentSession();
+      return session?.skippedSteps.includes(stepId) || false;
+    },
+    [getCurrentSession],
+  );
+
+  const getNextStep = useCallback(
+    (currentStepId: string): string | null => {
+      const step = config.flowConfig.steps.find((s) => s.id === currentStepId);
+      if (!step || step.index >= config.flowConfig.steps.length - 1)
+        return null;
+
+      const nextStep = config.flowConfig.steps.find(
+        (s) => s.index === step.index + 1,
+      );
+      return nextStep?.id || null;
+    },
+    [config.flowConfig.steps],
+  );
+
+  const getPreviousStep = useCallback(
+    (currentStepId: string): string | null => {
+      const step = config.flowConfig.steps.find((s) => s.id === currentStepId);
+      if (!step || step.index <= 0) return null;
+
+      const prevStep = config.flowConfig.steps.find(
+        (s) => s.index === step.index - 1,
+      );
+      return prevStep?.id || null;
+    },
+    [config.flowConfig.steps],
+  );
+
+  return {
+    // Flow control
+    startFlow,
+    completeFlow,
+    abandonFlow,
+
+    // Step tracking
+    trackStepViewed,
+    trackStepCompleted,
+    trackStepSkipped,
+    trackStepRetried,
+    trackStepHelp,
+
+    // Navigation
+    trackNavigation,
+
+    // State access
+    getCurrentSession,
+    getProgress,
+
+    // Utilities
+    isStepCompleted,
+    isStepSkipped,
+    getNextStep,
+    getPreviousStep,
+  };
+}