FlowAliveFlowAlive Docs
Get Started

React Native

Privacy-first mobile analytics for React Native apps. Track users, sessions and events | Flowalive Analytics

Installation

Install the SDK

npm install flowalive-analytics
bun add flowalive-analytics
yarn add flowalive-analytics
pnpm add flowalive-analytics

Install Required Peer Dependencies

Flowalive Analytics requires the following React Native packages to function properly:

npm install @react-native-async-storage/async-storage @react-native-community/netinfo react-native-device-info react-native-localize @react-navigation/native
bun add @react-native-async-storage/async-storage @react-native-community/netinfo react-native-device-info react-native-localize  @react-navigation/native
yarn add @react-native-async-storage/async-storage @react-native-community/netinfo react-native-device-info react-native-localize @react-navigation/native
pnpm add @react-native-async-storage/async-storage @react-native-community/netinfo react-native-device-info react-native-localize @react-navigation/native

These dependencies are required for the SDK to work correctly. The SDK uses:

  • @react-native-async-storage/async-storage - Local storage for offline event queuing
  • @react-native-community/netinfo - Network state monitoring
  • react-native-device-info - Device information collection
  • react-native-localize - Locale and timezone detection
  • @react-navigation/native - Automatic screen tracking (only needed if using trackNavigation)

Install iOS Dependencies

For iOS, install CocoaPods dependencies:

cd ios && pod install

Get Your API Key

  1. Sign in to Flowalive Dashboard
  2. Create a new project or select an existing one
  3. Open API Keys tab
  4. Copy your API Key (starts with flowalive_)

Setup

Wrap your app with the FlowaliveProvider component to initialize the SDK:

React
App.tsx
import { FlowaliveProvider } from 'flowalive-analytics/react-native';
import { NavigationContainer } from '@react-navigation/native';

export default function App() {
  return (
    <NavigationContainer>
      <FlowaliveProvider apiKey="flowalive_xxx">
        <YourApp />
      </FlowaliveProvider>
    </NavigationContainer>
  );
}

The FlowaliveProvider only initializes the SDK. You must call Flowalive.setDevice() before tracking events.

Configuration

The FlowaliveProvider component accepts the following props:

Prop

Type

Usage

Identify User

React
App.tsx
import { Flowalive } from 'flowalive-analytics/react-native';
import { useEffect } from 'react';

export default function App() {
  useEffect(() => {
    // Initialize analytics - no PII collected by default
    Flowalive.setDevice();
  }, []);

  return <YourApp />;
}

Adding custom properties:

// After user login and consent
await Flowalive.setDevice({
  appUserId: '123',
  appUserName: 'John Doe',
  appUserEmail: [EMAIL_ADDRESS]',
  metadata:{
    plan: 'premium',
    beta_tester: true
  }
});

Properties must be primitives: string, number, boolean, or null.

Track Events

// Event without parameters
Flowalive.track('app_opened');

// Event with parameters
Flowalive.track('purchase_completed', {
  amount: 99.99,
  currency: 'USD',
  product_id: 'premium_plan'
});

Event naming rules:

  • Alphanumeric characters, underscores (_), hyphens (-), periods (.), forward slashes (/), and spaces
  • 1-256 characters
  • Examples: purchase, user.signup, payment/success, Button Clicked

Event parameters:

  • Must be primitives: string, number, boolean, or null

Automatic Screen Tracking

Enable automatic screen tracking by setting trackNavigation to true and passing a navigationRef:

React
App.tsx
import { FlowaliveProvider } from 'flowalive-analytics/react-native';
import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';

const Stack = createNativeStackNavigator();

export default function App() {
  const navigationRef = useNavigationContainerRef();

  return (
    <NavigationContainer ref={navigationRef}>
      <FlowaliveProvider
        apiKey="flowalive_xxx"
        trackNavigation={true}
        navigationRef={navigationRef}
      >
        <Stack.Navigator>
          <Stack.Screen name="Home" component={HomeScreen} />
          <Stack.Screen name="Settings" component={SettingsScreen} />
        </Stack.Navigator>
      </FlowaliveProvider>
    </NavigationContainer>
  );
}

How it works:

  • Requires navigationRef from useNavigationContainerRef() hook
  • Pass the ref to both NavigationContainer and FlowaliveProvider
  • Automatically tracks screen views on navigation state changes
  • Screen names are converted from route names
  • Works with nested navigators and dynamic routes

Important: The navigationRef must be passed to both NavigationContainer and FlowaliveProvider for automatic tracking to work.

Type Reference

DeviceProperties

Custom user/device attributes passed to Flowalive.setDevice():

Prop

Type

EventParams

Event parameters passed to Flowalive.track():

Prop

Type

How It Works

Offline Support

Events are queued locally using @react-native-async-storage/async-storage when offline. The queue automatically syncs when connection is restored.

Performance

  • Offline events are batched and sent asynchronously
  • Network state is monitored via @react-native-community/netinfo
  • Failed requests retry with exponential backoff
  • Maximum batch size: 1000 events

On this page