React Native
Privacy-first mobile analytics for React Native apps. Track users, sessions and events | Flowalive Analytics
Installation
Install the SDK
npm install flowalive-analyticsbun add flowalive-analyticsyarn add flowalive-analyticspnpm add flowalive-analyticsInstall 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/nativebun add @react-native-async-storage/async-storage @react-native-community/netinfo react-native-device-info react-native-localize @react-navigation/nativeyarn add @react-native-async-storage/async-storage @react-native-community/netinfo react-native-device-info react-native-localize @react-navigation/nativepnpm add @react-native-async-storage/async-storage @react-native-community/netinfo react-native-device-info react-native-localize @react-navigation/nativeThese 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 monitoringreact-native-device-info- Device information collectionreact-native-localize- Locale and timezone detection@react-navigation/native- Automatic screen tracking (only needed if usingtrackNavigation)
Get Your API Key
- Sign in to Flowalive Dashboard
- Create a new project or select an existing one
- Open API Keys tab
- Copy your API Key (starts with
flowalive_)
Setup
Wrap your app with the FlowaliveProvider component to initialize the SDK:
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
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, ornull
Automatic Screen Tracking
Enable automatic screen tracking by setting trackNavigation to true and passing a navigationRef:
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
navigationReffromuseNavigationContainerRef()hook - Pass the ref to both
NavigationContainerandFlowaliveProvider - 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
