MetaRouter React Native SDK

The MetaRouter React Native SDK enables you to capture analytics events directly from your app and route them through the MetaRouter platform to your configured downstream integrations.

Built for performance, the SDK uses an internal queue to ensure all tracking calls are non-blocking and efficient. Events are batched and sent asynchronously to avoid impacting app performance.

👉 @metarouter/react-native-sdk on npm

Lifecycle

• Use createAnalyticsClient to initialize the analytics client.
• Use the initialized client or the MetaRouterProvider and useMetaRouter() hook to access analytics methods.

Installation Instructions

1.) Install MetaRouter SDK and Required Peer Dependencies:

Install SDK & Required Peer Dependencies

npm install @metarouter/react-native-sdk @react-native-async-storage/async-storage react-native-device-info

yarn add @metarouter/react-native-sdk @react-native-async-storage reaction native-device-info

pnpm add @metarouter/react-native-sdk @react-native-async-storage/async-storage react-native-device-info

These dependencies are required:

@react-native-async-storage/async-storage: used to persist user identity across sessions.

react-native-device-info: used to populate event context.

2.) Initialize the Analytics Client:

This is the minimum configuration required to use the analytics package within the MetaRouter SDK:

import {createAnalyticsClient} from '@metarouter/react-native-sdk'

const client = createAnalyticsClient({
        writeKey: 'mobile-sdk-test',
        ingestionHost: 'https://mr-platform.aws-us-east-1.mr-in.com',
      })

• writeKey: identifies the MetaRouter pipeline.
• ingestionHost: base URL of your MetaRouter ingestion infrastructure (e.g., https://mr-platform.aws-us-east-1.mr-in.com).
• flushInterval: flushes queued events every N seconds (default is 30).
• debug: enables verbose debug logging.

3.) Wrap Your App with MetaRouterProvider

To enable event tracking throughout your app, wrap your component tree with the MetaRouterProvider from the @metarouter/react-native-sdk package. This provides access to the analytics client via React context.

To enable analytics throughout your app, pass the client returned by createAnalyticsClient() to the MetaRouterProvider.
This makes the client available via React context using the useMetaRouter() hook.

This is typically done at the root level of your component hierarchy, alongside theming or navigation providers:

import { MetaRouterProvider, createAnalyticsClient } from '@metarouter/react-native-sdk';

const analyticsClient = createAnalyticsClient({
  writeKey: 'production-key',
  ingestionHost: 'https://platform.aws-us-east-1.mr-in.com',
});

const App = () => (
  <MetaRouterProvider analyticsClient={analyticsClient}>
    <YourApp />
  </MetaRouterProvider>
);

The analytics client returned by createAnalyticsClient() is at first a proxy — you can safely call .track() or .identify() even before initialization completes. All events are queued internally.

4.) Access Analytics Client

Option 1: React Hook Access (Recommended)
The easiest way to use the SDK is with the useMetaRouter hook, which provides access to the analytics client from anywhere in your React component tree:

import { useMetaRouter } from '@metarouter/react-native-sdk';

const MyComponent = () => {
  const { analytics } = useMetaRouter();

  useEffect(() => {
    analytics.track('Component Viewed');
  }, []);

  return <Text>Tracked</Text>;
};

Option 2: Programmatic Access
If you're outside of React (e.g., in utility functions or services), you can also access the proxy client directly:

import { createAnalyticsClient } from '@metarouter/react-native-sdk';

const analytics = createAnalyticsClient({...clientConfiguration}) 
analytics.track('Button Clicked');

Analytics Methods

📊 Event Tracking

analytics.track(event: string, props?: Record<string, any>);     // Track a custom user action
analytics.screen(name: string, props?: Record<string, any>);     // Track a screen view 
analytics.page(name: string, props?: Record<string, any>);       // Track a page view (web semantics)

👤 User Identity

analytics.identify(userId: string, traits?: Record<string, any>);  // Associate traits with a known user
analytics.alias(newUserId: string);                                // Merge anonymous and known user IDs
analytics.group(groupId: string, traits?: Record<string, any>);    // Associate the user with a group or org

🔄 Lifecycle & Utilities

analytics.flush();                  // Immediately send queued events
analytics.reset();                  // Reset client state (anonymousId, traits, queue)
analytics.getDebugInfo?.();         // Return internal state for debugging (optional method)