@formo/react-native-analytics

Formo Analytics SDK for React Native - Track wallet events and user analytics in mobile dApps.

Installation

npm install @formo/react-native-analytics @react-native-async-storage/async-storage

# or with yarn
yarn add @formo/react-native-analytics @react-native-async-storage/async-storage

# or with pnpm
pnpm add @formo/react-native-analytics @react-native-async-storage/async-storage

iOS Setup

cd ios && pod install

Quick Start

1. Wrap your app with the provider

import AsyncStorage from '@react-native-async-storage/async-storage';
import { FormoAnalyticsProvider } from '@formo/react-native-analytics';

function App() {
  return (
    <FormoAnalyticsProvider
      writeKey="your-write-key"
      asyncStorage={AsyncStorage}
      options={{
        app: {
          name: 'MyApp',
          version: '1.0.0',
        },
      }}
    >
      <YourApp />
    </FormoAnalyticsProvider>
  );
}

2. Use the hook in your components

import { useFormo } from '@formo/react-native-analytics';
import { useEffect } from 'react';

function HomeScreen() {
  const formo = useFormo();

  useEffect(() => {
    // Track screen view
    formo.screen('Home');
  }, []);

  const handleSignUp = () => {
    // Track custom event
    formo.track('Sign Up Button Pressed', {
      screen: 'Home',
    });
  };

  return <Button onPress={handleSignUp}>Sign Up</Button>;
}

Wagmi Integration

For dApps using Wagmi for wallet connections, you can enable automatic wallet event tracking:

import { QueryClient } from '@tanstack/react-query';
import { createConfig } from 'wagmi';
import AsyncStorage from '@react-native-async-storage/async-storage';
import { FormoAnalyticsProvider } from '@formo/react-native-analytics';

const queryClient = new QueryClient();
const wagmiConfig = createConfig({
  // your wagmi config
});

function App() {
  return (
    <FormoAnalyticsProvider
      writeKey="your-write-key"
      asyncStorage={AsyncStorage}
      options={{
        wagmi: {
          config: wagmiConfig,
          queryClient: queryClient,
        },
      }}
    >
      <YourApp />
    </FormoAnalyticsProvider>
  );
}

This automatically tracks:

• Wallet connections and disconnections
• Chain changes
• Signature requests (with QueryClient)
• Transaction events (with QueryClient)

API Reference

FormoAnalyticsProvider Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | writeKey | string | Yes | Your Formo write key | | asyncStorage | AsyncStorageInterface | Yes | AsyncStorage instance | | options | Options | No | Configuration options | | disabled | boolean | No | Disable analytics |

Options

interface Options {
  // Wagmi integration
  wagmi?: {
    config: any;      // Wagmi config from createConfig()
    queryClient?: any; // TanStack QueryClient for mutation tracking
  };

  // App information
  app?: {
    name?: string;
    version?: string;
    build?: string;
    bundleId?: string;
  };

  // Event batching
  flushAt?: number;       // Batch size (default: 20)
  flushInterval?: number; // Flush interval in ms (default: 30000)
  retryCount?: number;    // Retry count (default: 3)
  maxQueueSize?: number;  // Max queue size in bytes (default: 500KB)

  // Autocapture control
  autocapture?: boolean | {
    connect?: boolean;
    disconnect?: boolean;
    signature?: boolean;
    transaction?: boolean;
    chain?: boolean;
  };

  // Tracking control
  tracking?: boolean | {
    excludeChains?: number[];
  };

  // Logging
  logger?: {
    enabled?: boolean;
    levels?: ('debug' | 'info' | 'warn' | 'error' | 'log')[];
  };

  // Custom API host
  apiHost?: string;

  // Ready callback
  ready?: (formo: IFormoAnalytics) => void;
}

useFormo Hook Methods

screen(name, properties?, context?, callback?)

Track a screen view.

formo.screen('Profile', { userId: '123' });

track(event, properties?, context?, callback?)

Track a custom event.

formo.track('Purchase Completed', {
  revenue: 99.99,
  currency: 'USD',
  productId: 'nft-001',
});

identify(params, properties?, context?, callback?)

Identify a user by their wallet address.

formo.identify({
  address: '0x1234...',
  userId: 'user-123',
  providerName: 'MetaMask',
  rdns: 'io.metamask',
});

connect(params, properties?, context?, callback?)

Track wallet connection.

formo.connect({
  chainId: 1,
  address: '0x1234...',
});

disconnect(params?, properties?, context?, callback?)

Track wallet disconnection.

formo.disconnect({
  chainId: 1,
  address: '0x1234...',
});

chain(params, properties?, context?, callback?)

Track chain change.

formo.chain({
  chainId: 137,
  address: '0x1234...',
});

signature(params, properties?, context?, callback?)

Track signature event.

import { SignatureStatus } from '@formo/react-native-analytics';

formo.signature({
  status: SignatureStatus.CONFIRMED,
  chainId: 1,
  address: '0x1234...',
  message: 'Sign this message',
  signatureHash: '0xabcd...',
});

transaction(params, properties?, context?, callback?)

Track transaction event.

import { TransactionStatus } from '@formo/react-native-analytics';

formo.transaction({
  status: TransactionStatus.BROADCASTED,
  chainId: 1,
  address: '0x1234...',
  to: '0x5678...',
  value: '1000000000000000000',
  transactionHash: '0xdef...',
});

Consent Management

// Opt out of tracking (GDPR compliance)
formo.optOutTracking();

// Check opt-out status
const isOptedOut = formo.hasOptedOutTracking();

// Opt back in
formo.optInTracking();

Event Types

The SDK automatically enriches events with mobile-specific context:

• Device information (OS, version, model)
• Screen dimensions and density
• Locale and timezone
• App information (if provided)
• Anonymous ID (persistent across sessions)

Offline Support

Events are queued locally and sent when the device has network connectivity. Events are automatically flushed when:

• The batch size is reached (default: 20 events)
• The flush interval passes (default: 30 seconds)
• The app goes to background

License

MIT