react-native-unilitix

Official React Native SDK for Unilitix — African-first mobile UX analytics.

Install

npm install react-native-unilitix@^1.0.4
# or
yarn add react-native-unilitix@^1.0.4

Quick start

import Unilitix, { setupUnilitixCrashHandler } from 'react-native-unilitix';
import { useEffect } from 'react';

export default function App() {
  useEffect(() => {
    Unilitix.init('YOUR_API_KEY', { debug: true }).then(() => {
      setupUnilitixCrashHandler();
    });
  }, []);
}

Get your API key at app.unilitix.com → Settings → Apps → Create App.

Track events

Unilitix.track('purchase_completed', {
  amount: 5000,
  currency: 'NGN',
});

Identify users

// After login
Unilitix.identify('user_123', {
  name: 'Tosin',
  plan: 'pro',
  country: 'Nigeria',
});

// After logout
Unilitix.reset();

Screen tracking

Automatic screen tracking requires wiring the navigation listener:

import { createUnilitixNavigationListener } from 'react-native-unilitix';

<NavigationContainer onStateChange={createUnilitixNavigationListener()}>
  {/* your app */}
</NavigationContainer>

Note: The autoTrackScreens config option has no effect in React Native — all screens run inside a single Android Activity, so native lifecycle callbacks cannot detect React Navigation transitions. Always use createUnilitixNavigationListener or call Unilitix.screen() manually.

Crash tracking

Native crashes are captured automatically. For JS exception tracking, add:

import { setupUnilitixCrashHandler } from 'react-native-unilitix';

// Call once after init()
Unilitix.init('YOUR_API_KEY').then(() => {
  setupUnilitixCrashHandler();
});

Verify your integration

In debug mode, after init() resolves you will see in Metro console:

[Unilitix] ✅ SDK initialized
[Unilitix] ✅ Session started
[Unilitix] ⚠️ No screen events detected. Did you wire
Unilitix.screen() to NavigationContainer.onStateChange?

The ⚠️ warning only appears if Unilitix.screen() or createUnilitixNavigationListener is never called within 5 seconds of init. Wire the navigation listener to suppress it. Silent in production builds.

Configuration

await Unilitix.init('YOUR_API_KEY', {
  // Behaviour
  debug: true,
  autoTrackScreens: true,
  autoTrackTaps: true,
  autoTrackCrashes: true,
  autoTrackRageTaps: true,
  // Privacy
  maskInputs: true,
  captureSnapshots: true,       // session replay DOM snapshots
  captureScreenshots: true,     // session replay screenshots
  uploadScreenshotsOnWifiOnly: true,
  // Performance
  flushIntervalSeconds: 30,
  flushBatchSize: 100,
  maxOfflineEvents: 1000,
  sessionTimeoutSeconds: 1800,
  sampleRate: 1.0,
});

Privacy

Unilitix.optOut();  // stop tracking
Unilitix.optIn();   // resume tracking
Unilitix.reset();   // clear user identity

Session control

// Manually start a new session
await Unilitix.startSession();

// End the current session
await Unilitix.endSession();

// Force upload all queued events immediately
await Unilitix.flush();

Requirements

| Platform | Version | |--------------|--------------| | Android | API 21+ | | iOS | Gracefully no-ops — coming soon | | React Native | 0.71+ |