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)

📱 Advertising & Privacy

analytics.setAdvertisingId(advertisingId: string);     // Set device advertising ID (IDFA/GAID) for attribution
analytics.clearAdvertisingId();                        // Remove advertising ID from storage and context

Important Privacy Notes:
- Advertising IDs are Personally Identifiable Information (PII)
- Obtain user consent before collecting (iOS: ATT framework, Android: Play policies)
- Must comply with GDPR, CCPA, and App Store requirements

Usage Example:
// iOS - with App Tracking Transparency
import { AppTrackingTransparency } from 'react-native-tracking-transparency';

const status = await AppTrackingTransparency.requestTrackingAuthorization();
if (status === 'authorized') {
  const idfa = await getAdvertisingId();
  await analytics.setAdvertisingId(idfa);
}

// When user opts out
await analytics.clearAdvertisingId();

**Key details from the implementation:**

- **`setAdvertisingId(advertisingId: string)`** 
  - Persists the advertising ID to storage
  - Updates context for all subsequent events
  - Validates input (must be non-empty string)
  - Requires client to be initialized first

- **`clearAdvertisingId()`**
  - Removes advertising ID from storage and context
  - Useful for GDPR/CCPA compliance when users opt out
  - Does not affect other analytics data (unlike `reset()`)

Both methods are async and return Promises. The advertising ID is included in the `context.device.advertisingId` field of all events after being set.