Overview

The MetaRouter React Native SDK enables you to capture analytics events directly from your app. Once integrated, event data is forwarded to the MetaRouter platform and then routed to the downstream integrations you’ve configured in the connected pipeline.

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

MetaRouter’s React Native SDK uses the open-source Segment React Native library, which is a well-documented and widely-adopted SDK.

Installation Instructions

1.) Install Segment Analytics React Native SDK:

Follow the installation instructions provided by Segment:
https://segment.com/docs/connections/sources/catalog/libraries/mobile/react-native/

MetaRouter uses the Segment Analytics SDK and its DestinationPlugin architecture to efficiently route events to MetaRouter infrastructure. These instructions apply to major version 2.x.x of the Segment React Native SDK.

2.) Configure the Analytics Client:

This is the minimum configuration required to use the SDK with MetaRouter:

import { createClient} from '@segment/analytics-react-native';

const analyticsClient = createClient({
  writeKey: '',
  autoAddSegmentDestination: false,
});

• The writeKey is intentionally left blank because this implementation does not send data to Segment’s infrastructure. Instead, you’ll specify the appropriate writeKey for your MetaRouter pipeline in a later step.
• The autoAddSegmentDestination option must be set to false to ensure that events are not routed to Segment by default.

For additional configuration options, refer to Segment’s documentation.

3.) Create and Configure the MetaRouter Destination Plugin:

To route events through MetaRouter, you’ll need to configure a custom DestinationPlugin. This plugin does two key things:

1. Sets your MetaRouter ingestion endpoint as the destination for all analytics events.
2. Adds the appropriate writeKey to each event so that they can be correctly processed and routed to your configured downstream integrations.

All events will be sent to the /v1/t endpoint of your MetaRouter ingestion service. Events are forwarded to downstream vendors based on the type field in each event payload.

import { DestinationPlugin, SegmentEvent } from '@segment/analytics-react-native';

type MetaRouterEvent = SegmentEvent & {
  writeKey: string;
}

export class MetaRouterPlugin extends DestinationPlugin {
  private endpoint = '{{METAROUTER_INGESTION_ENDPOINT}}/v1/t';

  async execute(event: MetaRouterEvent) {
    const eventCopy = { ...event };
    eventCopy.writeKey = '{{METAROUTER_WRITE_KEY}}';

    await fetch(this.endpoint, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(eventCopy),
    });

    return event;
  }
}

4.) Apply the MetaRouter Destination Plugin

Use the analytics client you created earlier to add the MetaRouterPlugin:

analyticsClient.add({ plugin: new MetaRouterPlugin() });

5.) Wrap Your Application with AnalyticsProvider

To enable event tracking throughout your app, wrap your component tree with the AnalyticsProvider from the @segment/analytics-react-native package. This gives your app access to the analyticsClient via React context.

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

import { AnalyticsProvider} from '@segment/analytics-react-native';

  return (
    <ThemeProvider value={colorScheme === 'dark' ? DarkTheme : DefaultTheme}>
      <AnalyticsProvider client={analyticsClient}>
      <Stack>
        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
        <Stack.Screen name="+not-found" />
      </Stack>
      <StatusBar style="auto" />
      </AnalyticsProvider>
    </ThemeProvider>
  );

6.) Call Identify and Track Events

Once setup is complete, you can use the methods exposed by the Segment SDK to send events to your MetaRouter instance. The MetaRouterPlugin handles all standard Segment event types under the hood.

Refer to Segment’s documentation for more details: Segment React Native SDK – Implementation Guide

To use analytics methods in your components, import the useAnalytics hook. This is available anywhere in your app that is wrapped by the AnalyticsProvider.

import { useAnalytics } from '@segment/analytics-react-native';

const { identify, track } = useAnalytics();

Sample Identify Call

  const userId = '123456'; // Replace with actual user ID
  identify(userId, {
    email: '[email protected]',
    name: 'John Doe', 
  });

Sample Track Call (Tab Press)

 tabPress: (e) => {
          const tabPressed = e.target?.includes('index') ? 'shop' : 'account';
          track('Tab Pressed', { tab: tabPressed });
        },

Find more information about the React Native SDK at: https://segment.com/docs/connections/sources/catalog/libraries/mobile/react-native/