@formo/analytics-react-native 0.1.0

package/src/FormoAnalyticsProvider.tsx

@@ -0,0 +1,296 @@
+import React, {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  FC,
+} from "react";
+import { FormoAnalytics } from "./FormoAnalytics";
+import { initStorageManager } from "./lib/storage";
+import { logger } from "./lib/logger";
+import { FormoAnalyticsProviderProps, IFormoAnalytics } from "./types";
+
+// Default context with no-op methods
+const defaultContext: IFormoAnalytics = {
+  chain: () => Promise.resolve(),
+  screen: () => Promise.resolve(),
+  reset: () => {},
+  cleanup: () => Promise.resolve(),
+  detect: () => Promise.resolve(),
+  connect: () => Promise.resolve(),
+  disconnect: () => Promise.resolve(),
+  signature: () => Promise.resolve(),
+  transaction: () => Promise.resolve(),
+  identify: () => Promise.resolve(),
+  track: () => Promise.resolve(),
+  flush: () => Promise.resolve(),
+  setTrafficSourceFromUrl: () => {},
+  optOutTracking: () => {},
+  optInTracking: () => {},
+  hasOptedOutTracking: () => false,
+};
+
+export const FormoAnalyticsContext =
+  createContext<IFormoAnalytics>(defaultContext);
+
+/**
+ * Formo Analytics Provider for React Native
+ *
+ * Wraps your app to provide analytics context
+ *
+ * @example
+ * ```tsx
+ * import AsyncStorage from '@react-native-async-storage/async-storage';
+ * import { FormoAnalyticsProvider } from '@formo/analytics-react-native';
+ *
+ * function App() {
+ *   return (
+ *     <FormoAnalyticsProvider
+ *       writeKey="your-write-key"
+ *       asyncStorage={AsyncStorage}
+ *       options={{ wagmi: { config, queryClient } }}
+ *     >
+ *       <YourApp />
+ *     </FormoAnalyticsProvider>
+ *   );
+ * }
+ * ```
+ */
+export const FormoAnalyticsProvider: FC<FormoAnalyticsProviderProps> = (
+  props
+) => {
+  const { writeKey, disabled = false, children } = props;
+
+  if (!writeKey) {
+    logger.error("FormoAnalyticsProvider: No Write Key provided");
+    return (
+      <FormoAnalyticsContext.Provider value={defaultContext}>
+        {children}
+      </FormoAnalyticsContext.Provider>
+    );
+  }
+
+  if (disabled) {
+    logger.warn("FormoAnalytics is disabled");
+    return (
+      <FormoAnalyticsContext.Provider value={defaultContext}>
+        {children}
+      </FormoAnalyticsContext.Provider>
+    );
+  }
+
+  return <InitializedAnalytics {...props} />;
+};
+
+const InitializedAnalytics: FC<FormoAnalyticsProviderProps> = ({
+  writeKey,
+  options,
+  asyncStorage,
+  onReady,
+  onError,
+  children,
+}) => {
+  const [sdk, setSdk] = useState<IFormoAnalytics>(defaultContext);
+  const sdkRef = useRef<IFormoAnalytics>(defaultContext);
+  const storageInitKeyRef = useRef<string | null>(null);
+  const cleanupPromiseRef = useRef<Promise<void>>(Promise.resolve());
+  const initializationIdRef = useRef<number>(0);
+
+  // Only initialize storage manager when writeKey changes, not on every render
+  if (storageInitKeyRef.current !== writeKey) {
+    initStorageManager(writeKey);
+    storageInitKeyRef.current = writeKey;
+  }
+
+  // Store callbacks and options in refs to avoid re-initialization when references change
+  // This fixes the issue where inline arrow functions cause repeated SDK init
+  const onReadyRef = useRef(onReady);
+  const onErrorRef = useRef(onError);
+  const optionsRef = useRef(options);
+
+  // Update refs when values change (without triggering effect)
+  useEffect(() => {
+    onReadyRef.current = onReady;
+  }, [onReady]);
+
+  useEffect(() => {
+    onErrorRef.current = onError;
+  }, [onError]);
+
+  useEffect(() => {
+    optionsRef.current = options;
+  }, [options]);
+
+  // Extract individual option values to avoid reference equality issues with options object
+  const tracking = options?.tracking;
+  const autocapture = options?.autocapture;
+  const apiHost = options?.apiHost;
+  const flushAt = options?.flushAt;
+  const flushInterval = options?.flushInterval;
+  const retryCount = options?.retryCount;
+  const maxQueueSize = options?.maxQueueSize;
+  const loggerOption = options?.logger;
+  const app = options?.app;
+  const hasReady = !!options?.ready;
+  const wagmiConfig = options?.wagmi?.config;
+  const wagmiQueryClient = options?.wagmi?.queryClient;
+
+  // Create stable key from serializable options
+  const optionsKey = useMemo(() => {
+    const serializableOptions = {
+      tracking,
+      autocapture,
+      apiHost,
+      flushAt,
+      flushInterval,
+      retryCount,
+      maxQueueSize,
+      logger: loggerOption,
+      app,
+      hasReady,
+    };
+
+    try {
+      return JSON.stringify(serializableOptions);
+    } catch (error) {
+      logger.warn("Failed to serialize options, using timestamp", error);
+      return Date.now().toString();
+    }
+  }, [tracking, autocapture, apiHost, flushAt, flushInterval, retryCount, maxQueueSize, loggerOption, app, hasReady]);
+
+  useEffect(() => {
+    // Increment initialization ID to track which initialization is current
+    const currentInitId = ++initializationIdRef.current;
+    let isCleanedUp = false;
+
+    const initialize = async () => {
+      // Wait for any pending cleanup to complete before re-initializing
+      // This prevents race conditions between cleanup and init
+      await cleanupPromiseRef.current;
+
+      // Check if this initialization is still current after awaiting cleanup
+      if (currentInitId !== initializationIdRef.current || isCleanedUp) {
+        logger.debug("Skipping stale initialization");
+        return;
+      }
+
+      // Clean up existing SDK and await flush completion
+      if (sdkRef.current && sdkRef.current !== defaultContext) {
+        logger.log("Cleaning up existing FormoAnalytics SDK instance");
+        const cleanup = sdkRef.current.cleanup();
+        cleanupPromiseRef.current = cleanup;
+        await cleanup;
+        sdkRef.current = defaultContext;
+        setSdk(defaultContext);
+      }
+
+      // Check again after cleanup
+      if (currentInitId !== initializationIdRef.current || isCleanedUp) {
+        logger.debug("Skipping stale initialization after cleanup");
+        return;
+      }
+
+      try {
+        // Use optionsRef.current to ensure we have the latest options
+        const sdkInstance = await FormoAnalytics.init(
+          writeKey,
+          optionsRef.current,
+          asyncStorage
+        );
+
+        // Verify this initialization is still current
+        if (currentInitId !== initializationIdRef.current || isCleanedUp) {
+          logger.log("Initialization superseded, cleaning up new instance");
+          await sdkInstance.cleanup();
+          return;
+        }
+
+        setSdk(sdkInstance);
+        sdkRef.current = sdkInstance;
+        logger.log("Successfully initialized FormoAnalytics SDK");
+
+        // Call onReady callback using the ref (stable reference)
+        onReadyRef.current?.(sdkInstance);
+      } catch (error) {
+        if (currentInitId === initializationIdRef.current && !isCleanedUp) {
+          logger.error("Failed to initialize FormoAnalytics SDK", error);
+          // Call onError callback using the ref (stable reference)
+          onErrorRef.current?.(error instanceof Error ? error : new Error(String(error)));
+        }
+      }
+    };
+
+    initialize();
+
+    return () => {
+      isCleanedUp = true;
+
+      if (sdkRef.current && sdkRef.current !== defaultContext) {
+        logger.log("Cleaning up FormoAnalytics SDK instance");
+        // Store cleanup promise so next initialization can await it
+        const cleanup = sdkRef.current.cleanup().catch((error) => {
+          logger.error("Error during SDK cleanup:", error);
+        });
+        cleanupPromiseRef.current = cleanup;
+        sdkRef.current = defaultContext;
+      }
+    };
+    // Note: onReady and onError are NOT in the dependency array
+    // They are accessed via refs to prevent re-initialization
+    // wagmiConfig and wagmiQueryClient are tracked separately since they're not serializable
+  }, [writeKey, optionsKey, asyncStorage, wagmiConfig, wagmiQueryClient]);
+
+  return (
+    <FormoAnalyticsContext.Provider value={sdk}>
+      {children}
+    </FormoAnalyticsContext.Provider>
+  );
+};
+
+/**
+ * Hook to access Formo Analytics
+ *
+ * @example
+ * ```tsx
+ * import { useFormo } from '@formo/analytics-react-native';
+ *
+ * function MyScreen() {
+ *   const formo = useFormo();
+ *
+ *   useEffect(() => {
+ *     formo.screen('Home');
+ *   }, []);
+ *
+ *   const handleButtonPress = () => {
+ *     formo.track('Button Pressed', { buttonName: 'signup' });
+ *   };
+ *
+ *   return <Button onPress={handleButtonPress}>Sign Up</Button>;
+ * }
+ * ```
+ */
+// Track if the useFormo warning has been logged to avoid console spam
+let hasLoggedUseFormoWarning = false;
+
+export const useFormo = (): IFormoAnalytics => {
+  const context = useContext(FormoAnalyticsContext);
+
+  // Check if SDK has been initialized (context will be defaultContext before init completes)
+  // Only log the warning once to avoid flooding the console during async initialization
+  if (context === defaultContext && !hasLoggedUseFormoWarning) {
+    hasLoggedUseFormoWarning = true;
+    logger.warn(
+      "useFormo called before SDK initialization complete. " +
+        "Ensure FormoAnalyticsProvider is mounted and writeKey is provided."
+    );
+  }
+
+  // Reset the warning flag when SDK is initialized so it can warn again after a reset
+  if (context !== defaultContext) {
+    hasLoggedUseFormoWarning = false;
+  }
+
+  return context;
+};

package/src/constants/config.ts

@@ -0,0 +1,62 @@
+export const EVENTS_API_ORIGIN = "https://events.formo.so";
+export const EVENTS_API_HOST = `${EVENTS_API_ORIGIN}/v0/raw_events`;
+
+export const EVENTS_API_REQUEST_HEADER = (writeKey: string) => ({
+  "Content-Type": "application/json",
+  Authorization: `Bearer ${writeKey}`,
+});
+
+// Timezone to country mapping
+export const COUNTRY_LIST: Record<string, string> = {
+  // Africa
+  "Africa/Abidjan": "CI",
+  "Africa/Accra": "GH",
+  "Africa/Addis_Ababa": "ET",
+  "Africa/Algiers": "DZ",
+  "Africa/Cairo": "EG",
+  "Africa/Casablanca": "MA",
+  "Africa/Johannesburg": "ZA",
+  "Africa/Lagos": "NG",
+  "Africa/Nairobi": "KE",
+  // America
+  "America/Anchorage": "US",
+  "America/Argentina/Buenos_Aires": "AR",
+  "America/Bogota": "CO",
+  "America/Chicago": "US",
+  "America/Denver": "US",
+  "America/Los_Angeles": "US",
+  "America/Mexico_City": "MX",
+  "America/New_York": "US",
+  "America/Phoenix": "US",
+  "America/Sao_Paulo": "BR",
+  "America/Toronto": "CA",
+  "America/Vancouver": "CA",
+  // Asia
+  "Asia/Bangkok": "TH",
+  "Asia/Dubai": "AE",
+  "Asia/Ho_Chi_Minh": "VN",
+  "Asia/Hong_Kong": "HK",
+  "Asia/Jakarta": "ID",
+  "Asia/Kolkata": "IN",
+  "Asia/Manila": "PH",
+  "Asia/Seoul": "KR",
+  "Asia/Shanghai": "CN",
+  "Asia/Singapore": "SG",
+  "Asia/Taipei": "TW",
+  "Asia/Tokyo": "JP",
+  // Australia
+  "Australia/Melbourne": "AU",
+  "Australia/Sydney": "AU",
+  // Europe
+  "Europe/Amsterdam": "NL",
+  "Europe/Berlin": "DE",
+  "Europe/London": "GB",
+  "Europe/Madrid": "ES",
+  "Europe/Moscow": "RU",
+  "Europe/Paris": "FR",
+  "Europe/Rome": "IT",
+  "Europe/Zurich": "CH",
+  // Pacific
+  "Pacific/Auckland": "NZ",
+  "Pacific/Honolulu": "US",
+};

package/src/constants/events.ts

@@ -0,0 +1,26 @@
+export enum EventType {
+  PAGE = "page",
+  SCREEN = "screen",
+  IDENTIFY = "identify",
+  DETECT = "detect",
+  CONNECT = "connect",
+  DISCONNECT = "disconnect",
+  CHAIN = "chain",
+  SIGNATURE = "signature",
+  TRANSACTION = "transaction",
+  TRACK = "track",
+}
+
+export enum EventChannel {
+  WEB = "web",
+  MOBILE = "mobile",
+  SERVER = "server",
+  SOURCE = "source",
+}
+
+export type TEventType = Lowercase<EventType>;
+export type TEventChannel = Lowercase<EventChannel>;
+
+// React Native SDK uses mobile channel
+export const CHANNEL: TEventChannel = "mobile";
+export const VERSION = "1";

package/src/constants/index.ts

@@ -0,0 +1,3 @@
+export * from "./events";
+export * from "./config";
+export * from "./storage";

package/src/constants/storage.ts

@@ -0,0 +1,16 @@
+// Storage keys for React Native SDK
+export const STORAGE_PREFIX = "formo_rn_";
+
+// Local storage keys (persistent)
+export const LOCAL_ANONYMOUS_ID_KEY = "anonymous_id";
+export const LOCAL_APP_VERSION_KEY = "app_version";
+export const LOCAL_APP_BUILD_KEY = "app_build";
+
+// Session storage keys (cleared on app restart)
+export const SESSION_USER_ID_KEY = "user_id";
+export const SESSION_TRAFFIC_SOURCE_KEY = "traffic_source";
+export const SESSION_WALLET_DETECTED_KEY = "wallet_detected";
+export const SESSION_WALLET_IDENTIFIED_KEY = "wallet_identified";
+
+// Consent keys
+export const CONSENT_OPT_OUT_KEY = "opt_out_tracking";

package/src/index.ts

@@ -0,0 +1,55 @@
+/**
+ * Formo Analytics SDK for React Native
+ *
+ * Track wallet events and user analytics in mobile dApps
+ *
+ * @example
+ * ```tsx
+ * import AsyncStorage from '@react-native-async-storage/async-storage';
+ * import { FormoAnalyticsProvider, useFormo } from '@formo/analytics-react-native';
+ *
+ * // Wrap your app with the provider
+ * function App() {
+ *   return (
+ *     <FormoAnalyticsProvider
+ *       writeKey="your-write-key"
+ *       asyncStorage={AsyncStorage}
+ *       options={{
+ *         wagmi: { config, queryClient },
+ *         app: { name: 'MyApp', version: '1.0.0' },
+ *       }}
+ *     >
+ *       <YourApp />
+ *     </FormoAnalyticsProvider>
+ *   );
+ * }
+ *
+ * // Use the hook in your components
+ * function MyScreen() {
+ *   const formo = useFormo();
+ *
+ *   useEffect(() => {
+ *     formo.screen('Home');
+ *   }, []);
+ *
+ *   return <View>...</View>;
+ * }
+ * ```
+ */
+
+// Main exports
+export { FormoAnalytics } from "./FormoAnalytics";
+export {
+  FormoAnalyticsProvider,
+  FormoAnalyticsContext,
+  useFormo,
+} from "./FormoAnalyticsProvider";
+
+// Types
+export * from "./types";
+
+// Event types for manual event tracking
+export { SignatureStatus, TransactionStatus } from "./types/events";
+
+// Storage types for custom storage implementations
+export type { AsyncStorageInterface } from "./lib/storage";

package/src/lib/consent/index.ts

@@ -0,0 +1,52 @@
+import { storage } from "../storage";
+import { logger } from "../logger";
+
+/**
+ * Get consent storage key
+ * Note: The storage adapter already prefixes keys with formo_rn_{writeKey}_
+ * so we just need a simple consent prefix here
+ */
+function getConsentKey(_writeKey: string, key: string): string {
+  return `consent_${key}`;
+}
+
+/**
+ * Set a consent flag
+ */
+export function setConsentFlag(
+  writeKey: string,
+  key: string,
+  value: string
+): void {
+  try {
+    const consentKey = getConsentKey(writeKey, key);
+    storage().set(consentKey, value);
+  } catch (error) {
+    logger.error("Consent: Failed to set flag", error);
+  }
+}
+
+/**
+ * Get a consent flag
+ */
+export function getConsentFlag(writeKey: string, key: string): string | null {
+  try {
+    const consentKey = getConsentKey(writeKey, key);
+    return storage().get(consentKey);
+  } catch (error) {
+    logger.error("Consent: Failed to get flag", error);
+    return null;
+  }
+}
+
+/**
+ * Remove a consent flag
+ */
+export function removeConsentFlag(writeKey: string, key: string): void {
+  try {
+    const consentKey = getConsentKey(writeKey, key);
+    storage().remove(consentKey);
+  } catch (error) {
+    logger.error("Consent: Failed to remove flag", error);
+  }
+}