React Native

Installation

Install the SDK

npm

bun

yarn

pnpm

npm install phase-analytics

bun add phase-analytics

yarn add phase-analytics

pnpm add phase-analytics

Install Required Peer Dependencies

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

npm

bun

yarn

pnpm

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 Phase Dashboard
2. Create a new project or select an existing one
3. Open API Keys tab
4. Copy your API Key (starts with phase_)

Setup

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

import { PhaseProvider } from 'phase-analytics/react-native';
import { NavigationContainer } from '@react-navigation/native';

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

The PhaseProvider only initializes the SDK. You must call Phase.identify() before tracking events.

Configuration

The PhaseProvider component accepts the following props:

Usage

Identify User

Required: Call Phase.identify() before using any other methods. This registers the device and starts a session.

import { Phase } from 'phase-analytics/react-native';
import { useEffect } from 'react';

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

  return <YourApp />;
}

Privacy by default:

• No personal data is collected without explicit properties
• Device ID is auto-generated and stored locally
• Only technical metadata is collected (OS version, platform, locale)

Adding custom properties:

You can optionally attach user properties. Important: If you add PII (personally identifiable information), ensure you have proper user consent:

// After user login and consent
await Phase.identify({
  user_id: '123',
  plan: 'premium',
  beta_tester: true
});

// ⚠️ If adding PII, get consent first
const hasConsent = await customGetUserConsent();
if (hasConsent) {
  await Phase.identify({
    email: '[email protected]',
    name: 'John Doe'
  });
}

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

Track Events

Track custom events with optional parameters. Note: Phase.identify() must be called first.

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

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

Event naming rules:

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

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:

import { PhaseProvider } from 'phase-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}>
      <PhaseProvider
        apiKey="phase_xxx"
        trackNavigation={true}
        navigationRef={navigationRef}
      >
        <Stack.Navigator>
          <Stack.Screen name="Home" component={HomeScreen} />
          <Stack.Screen name="Settings" component={SettingsScreen} />
        </Stack.Navigator>
      </PhaseProvider>
    </NavigationContainer>
  );
}

How it works:

• Requires navigationRef from useNavigationContainerRef() hook
• Pass the ref to both NavigationContainer and PhaseProvider
• 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 PhaseProvider for automatic tracking to work.

Type Reference

DeviceProperties

Custom user/device attributes passed to Phase.identify():

EventParams

Event parameters passed to Phase.track():

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.

Privacy

• No personal data is collected by default
• Device IDs are generated locally and stored persistently
• Geolocation is resolved server-side from IP address (disable with properties)
• All data collection is optional via configuration

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