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 MetaRouter.analytics.init() to initialize the analytics client.
• Use MetaRouter.analytics.getClient() or the MetaRouterProvider and useMetaRouter() hook to access analytics methods.
• Use MetaRouter.analytics.reset() to reset or reinitialize the client.

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 {MetaRouter} from '@metarouter/react-native-sdk'

MetaRouter.analytics.init({
        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.

Unlike some other SDKs, you should pass the full MetaRouter object, not the result of init(). The internal client is resolved via .analytics.getClient() in the hook.

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

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

MetaRouter.analytics.init({
  writeKey: 'production-key',
  ingestionHost: 'https://platform.aws-us-east-1.mr-in.com',
});

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

ℹ️ The MetaRouterProvider does not require init() to complete before rendering. The analytics client is internally proxied, so any tracking calls made before or after initialization will be safely queued and sent once ready.

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>;
};

• ✅ The client returned by analytics.getClient() is a proxy that safely queues events until the SDK is fully initialized.
  You don’t need to worry about the timing of init() in your component logic.

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 { MetaRouter } from '@metarouter/react-native-sdk';

const analytics = MetaRouter.analytics.getClient();  
analytics.track('Button Clicked');

Calls made before MetaRouter.analytics.init() completes will be safely queued and sent once the client is ready.

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.cleanup();                // Stop timers, listeners, and clear resources
analytics.getDebugInfo?.();         // Return internal state for debugging (optional method)