@croacroa/react-native-template 2.1.0 → 3.2.0

package/services/analytics/analytics-adapter.ts

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Analytics adapter facade
+ * Delegates all analytics calls to the pre-existing multi-provider analytics
+ * system in `@/services/analytics` so there is a single source of truth.
+ *
+ * Consumers that import `Analytics` from this module (e.g. AnalyticsProvider,
+ * useTrackScreen, useTrackEvent) will ultimately go through the same pipeline
+ * as direct callers of `@/services/analytics`.
+ *
+ * @module services/analytics/analytics-adapter
+ */
+
+import {
+  track,
+  screen,
+  identify,
+  resetAnalytics,
+  setUserProperties,
+} from "@/services/analytics";
+import type { AnalyticsConfig } from "./types";
+
+// ============================================================================
+// Module-level state
+// ============================================================================
+
+/** Runtime configuration */
+let config: AnalyticsConfig = {
+  enabled: true,
+  debug: __DEV__,
+};
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Central analytics facade.
+ *
+ * Every method delegates to the pre-existing multi-provider analytics singleton
+ * exported from `@/services/analytics`.
+ */
+export const Analytics = {
+  /**
+   * Merge new configuration values.
+   */
+  configure(newConfig: Partial<AnalyticsConfig>): void {
+    config = { ...config, ...newConfig };
+
+    if (config.debug) {
+      console.log("[Analytics] Configured:", config);
+    }
+  },
+
+  /**
+   * Initialize analytics. The underlying system auto-initializes adapters on
+   * import, so this is effectively a no-op but kept for API compatibility.
+   */
+  async initialize(): Promise<void> {
+    if (!config.enabled) return;
+    if (config.debug) {
+      console.log("[Analytics] Initialized (delegating to services/analytics)");
+    }
+  },
+
+  /** Track a named event with optional properties. */
+  track(event: string, properties?: Record<string, unknown>): void {
+    if (!config.enabled) return;
+    track(event, properties);
+  },
+
+  /** Track a screen view. */
+  screen(name: string, properties?: Record<string, unknown>): void {
+    if (!config.enabled) return;
+    screen(name, properties);
+  },
+
+  /** Identify the current user. */
+  identify(userId: string, traits?: Record<string, unknown>): void {
+    if (!config.enabled) return;
+    identify(userId, traits);
+  },
+
+  /** Reset analytics state (e.g. on sign out). */
+  reset(): void {
+    if (!config.enabled) return;
+    resetAnalytics();
+  },
+
+  /** Set persistent user properties. */
+  setUserProperties(properties: Record<string, unknown>): void {
+    if (!config.enabled) return;
+    setUserProperties(properties);
+  },
+};

package/services/analytics/types.ts

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Analytics type definitions
+ * Defines the adapter interface and configuration for the analytics system.
+ * @module services/analytics/types
+ */
+
+// ============================================================================
+// Adapter Interface
+// ============================================================================
+
+/**
+ * Interface that all analytics adapters must implement.
+ * Swap adapters to switch between providers (Mixpanel, Amplitude, etc.)
+ * without changing application code.
+ */
+export interface AnalyticsAdapter {
+  /**
+   * Initialize the analytics provider.
+   * Called once when the app starts.
+   */
+  initialize(): Promise<void> | void;
+
+  /**
+   * Track a custom event with optional properties.
+   *
+   * @param event - The event name (e.g. "Button Clicked")
+   * @param properties - Additional key-value data to attach to the event
+   */
+  track(event: string, properties?: Record<string, unknown>): void;
+
+  /**
+   * Track a screen view.
+   *
+   * @param name - The screen name or route path
+   * @param properties - Additional data such as route segments
+   */
+  screen(name: string, properties?: Record<string, unknown>): void;
+
+  /**
+   * Identify the current user.
+   *
+   * @param userId - Unique identifier for the user
+   * @param traits - Optional user traits (email, name, plan, etc.)
+   */
+  identify(userId: string, traits?: Record<string, unknown>): void;
+
+  /**
+   * Reset analytics state (e.g. on sign out).
+   * Clears the identified user and any queued data.
+   */
+  reset(): void;
+
+  /**
+   * Set persistent user properties that are sent with every subsequent event.
+   *
+   * @param properties - Key-value pairs to persist
+   */
+  setUserProperties(properties: Record<string, unknown>): void;
+}
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+/**
+ * Runtime configuration for the analytics system.
+ */
+export interface AnalyticsConfig {
+  /** Whether analytics tracking is enabled */
+  enabled: boolean;
+  /** Whether to log debug information to the console */
+  debug: boolean;
+}