MetaRouter React Native SDK

Capture behavioral data directly from your React Native app and route it through MetaRouter to any destination — without juggling multiple vendor SDKs.

View on GitHub

Why use the Mobile SDK?

One integration, unlimited destinations
Stop embedding separate SDKs for analytics, marketing, and data warehouses. Collect once, route everywhere through MetaRouter.

Update routing without app releases
Add or remove destinations server-side. No code changes, no app store review cycles.

Reliable delivery, even offline
Events are batched and delivered with built-in retry logic. Circuit breaker patterns handle transient failures gracefully.

Automatic identity resolution
Track users from first app open through sign-up and beyond. The SDK manages anonymous IDs, persists identity across sessions, and connects pre-login activity to known users.

Privacy-ready by design
Built-in support for advertising ID consent, easy opt-out handling, and clean user data reset for GDPR/CCPA compliance.

Lightweight footprint
Minimal dependencies. Small impact on bundle size and startup time.

Quick start

1) Install the SDK

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

2) Initialize

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

const analytics = await createAnalyticsClient({
  writeKey: "YOUR_WRITE_KEY",
  ingestionHost: "https://YOUR_CLUSTER.mr-in.com",
});

Your writeKey and ingestionHost are available in the MetaRouter dashboard.

3) Start tracking

// Track user actions
analytics.track("Product Viewed", {
  sku: "SHOE-123",
  price: 89.99,
});

// Identify known users
analytics.identify("user-456", {
  email: "[email protected]",
  plan: "premium",
});

// Track screen views
analytics.screen("Product Detail", {
  category: "Footwear",
});

Events are batched and delivered automatically. No additional setup required.

Core capabilities

Event tracking

Method	Purpose
`track(event, properties)`	Capture user actions — purchases, clicks, feature usage
`screen(name, properties)`	Record screen views for navigation analytics
`page(name, properties)`	Record page views (web semantics, if applicable)

User identity

Method	Purpose
`identify(userId, traits)`	Associate events with a known user
`group(groupId, traits)`	Associate users with a company, team, or account
`alias(newUserId)`	Link anonymous activity to a newly identified user

Lifecycle & privacy

Method	Purpose
`flush()`	Send queued events immediately
`reset()`	Clear all user data (use on logout)
`setAdvertisingId(id)`	Set IDFA/GAID for attribution (with user consent)
`clearAdvertisingId()`	Remove advertising ID when user opts out

Identity that just works

The SDK automatically handles the complexity of user identity:

Before login — Users are assigned a stable anonymous ID (UUID v4)
On login — Call identify() to attach a known user ID
Across sessions — Identity persists through app restarts via AsyncStorage
On logout — Call reset() to clear everything and start fresh

Connect anonymous browsing to authenticated users with alias():

// User browses anonymously, then signs up
analytics.track("Product Viewed", { sku: "ABC" }); // tracked as anonymous

// User creates account
analytics.alias("new-user-789"); // links anonymous → known
analytics.identify("new-user-789", { email: "[email protected]" });

// Full journey is now connected in your downstream tools

Advertising & attribution

For ad attribution, you can include the platform advertising ID:

// Only after obtaining user consent
// iOS: IDFA | Android: GAID
analytics.setAdvertisingId(advertisingId);

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

Privacy note: Always obtain explicit consent before collecting advertising IDs iOS — Use the App Tracking Transparency framework to request permission Android — Respect the user’s ad personalization settings

React Hooks

Use the provider and hook for easy access throughout your app:

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

// In your App component
const App = () => {
  const [analytics, setAnalytics] = useState(null);

  useEffect(() => {
    createAnalyticsClient({
      writeKey: "YOUR_WRITE_KEY",
      ingestionHost: "https://YOUR_CLUSTER.mr-in.com",
    }).then(setAnalytics);
  }, []);

  if (!analytics) return null;

  return (
    <MetaRouterProvider analyticsClient={analytics}>
      <YourApp />
    </MetaRouterProvider>
  );
};

// In any component
const ProductScreen = () => {
  const { analytics } = useMetaRouter();

  const handlePurchase = () => {
    analytics.track("Purchase Completed", { amount: 99.99 });
  };

  return <Button onPress={handlePurchase} title="Buy Now" />;
};

Configuration options

const analytics = await createAnalyticsClient({
  writeKey: "YOUR_WRITE_KEY",            // Required
  ingestionHost: "https://...",          // Required
  flushIntervalSeconds: 10,              // Optional (default: 10)
  maxQueueEvents: 2000,                  // Optional (default: 2000)
  debug: false,                          // Optional (default: false)
});

Option	Description
`writeKey`	Your MetaRouter write key
`ingestionHost`	Your ingestion endpoint (no trailing slash)
`flushIntervalSeconds`	How often to send batched events
`maxQueueEvents`	Maximum events to queue before dropping oldest
`debug`	Enable verbose logging

Requirements

Component	Version
React Native	0.63+
React	16.8+
iOS	9.0+ (13.4+ with New Architecture)
Android	API 23+ (6.0 Marshmallow)

Peer dependencies

Package	Version
`@react-native-async-storage/async-storage`	2.2.0+
`react-native-device-info`	14.0.4+