Analytics for React Native

To get started with the Analytics for React Native library:

1. Create a React Native Source in Segment.

   1. Go to Connections > Sources > Add source.
   2. Search for "React Native" and click Add Source.

2. Install @segment/analytics-react-native, @segment/sovran-react-native and react-native-get-random-values. You can install in one of two ways:

   Copy code block

   yarn add @segment/analytics-react-native @segment/sovran-react-native react-native-get-random-values

   or

   Copy code block

   npm install --save @segment/analytics-react-native @segment/sovran-react-native react-native-get-random-values

3. If you want to use the default persistor for the Segment Analytics client, you also have to install react-native-async-storage/async-storage. You can install in one of two ways:

   Copy code block

   yarn add @react-native-async-storage/async-storage 

   or

   Copy code block

   npm install --save @react-native-async-storage/async-storage

   To use your own persistence layer you can use the storePersistor option when initializing the client. Make sure you always have a persistor, either by having AsyncStorage package installed or by explicitly passing a value, or you might get unexpected side effects like multiple 'Application Installed' events.

4. If you're using iOS, install native modules with:

   Copy code block

   npx pod-install

5. If you're using Android, you need to add extra permissions to your AndroidManifest.xml.

   Copy code block

   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

6. Initialize and configure the Analytics React Native client. The package exposes a method called createClient which you can use to create the Segment Analytics client. This central client manages all the tracking events.

   Copy code block

   1
   import { createClient, AnalyticsProvider } from '@segment/analytics-react-native';
   2
   
   3
   const segmentClient = createClient({
   4
     writeKey: 'SEGMENT_API_KEY'
   5
   });

These are the options you can apply to configure the client:

You can add a plugin at any time using segmentClient.add(). More information about plugins, including a detailed architecture overview and a guide to creating your own, can be found in the Analytics React Native Plugin Architecture docs.

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

3
import { AmplitudeSessionPlugin } from '@segment/analytics-react-native-plugin-amplitude-session';
4
import { FirebasePlugin } from '@segment/analytics-react-native-plugin-firebase';
5
import { IdfaPlugin } from '@segment/analytics-react-native-plugin-idfa';
6

7
const segmentClient = createClient({
8
  writeKey: 'SEGMENT_KEY'
9
});
10

11
segmentClient.add({ plugin: new AmplitudeSessionPlugin() });
12
segmentClient.add({ plugin: new FirebasePlugin() });
13
segmentClient.add({ plugin: new IdfaPlugin() });

You can use Analytics React Native with or without hooks.

To use the useAnalytics hook within the application, wrap the application in an AnalyticsProvider. This uses the Context API which allows access to the analytics client anywhere in the application.

1
import {
2
  createClient,
3
  AnalyticsProvider,
4
} from '@segment/analytics-react-native';
5

6
const segmentClient = createClient({
7
  writeKey: 'SEGMENT_API_KEY'
8
});
9

10
const App = () => (
11
  <AnalyticsProvider client={segmentClient}>
12
    <Content />
13
  </AnalyticsProvider>
14
);

The useAnalytics() hook exposes the client methods:

1
import React from 'react';
2
import { Text, TouchableOpacity } from 'react-native';
3
import { useAnalytics } from '@segment/analytics-react-native';
4

5
const Button = () => {
6
  const { track } = useAnalytics();
7
  return (
8
    <TouchableOpacity
9
      style={styles.button}
10
      onPress={() => {
11
        track('Awesome event');
12
      }}
13
    >
14
      <Text style={styles.text}>Press me!</Text>
15
    </TouchableOpacity>
16
  );
17
};

To use the tracking events without hooks, call the methods directly on the client:

1
import {
2
  createClient,
3
  AnalyticsProvider,
4
} from '@segment/analytics-react-native';
5

6
// create the client once when the app loads
7
const segmentClient = createClient({
8
  writeKey: 'SEGMENT_API_KEY'
9
});
10

11
// track an event using the client instance
12
segmentClient.track('Awesome event');

track: (event: string, properties?: JsonMap) => void;

1
const { track } = useAnalytics();
2

3
track('View Product', {
4
  productId: 123,
5
  productName: 'Striped trousers',
6
});

Once you've installed the Analytics React Native library, you can start collecting data through Segment's tracking methods:

• Track
• Identify
• Screen
• Group
• Alias

Destinations are the business tools or apps that Segment sends your data to. Adding destinations allows you to act on your data and learn more about your customers in real time.

Segment offers support for two different types of destination connection modes: cloud-mode and device-mode. Learn more about the differences between the two in the Segment destination docs.

The Analytics React Native 2.0 utility methods help you to manage your data. They include:

• Alias
• Reset
• Flush
• Cleanup

The Alias method is used to merge two user identities by connecting two sets of user data as one. This method is required to manage user identities in some of Segment's destinations.

alias: (newUserId: string) => void;

1
const { alias } = useAnalytics();
2

3
alias('user-123');

The Reset method clears the internal state of the library for the current user and group. This is useful for apps where users can log in and out with different identities over time.

reset: () => void;

1
const { reset } = useAnalytics();
2

3
reset();

By default, the analytics client sends queued events to the API every 30 seconds or when 20 events accumulate, whichever occurs first. This also occurs whenever the app resumes if the user has closed the app with some events unsent. These values can be modified by the flushAt and flushInterval config options. You can also trigger a flush event manually.

flush: () => Promise<void>;

1
const { flush } = useAnalytics();
2

3
flush();

If you've called createClient more than once for the same client in your application lifecycle, use this method on the old client to clear any subscriptions and timers first.

1
let client = createClient({
2
  writeKey: 'KEY'
3
});
4

5
client.cleanup();
6

7
client = createClient({
8
  writeKey: 'KEY'
9
});

If you don't do this, the old client instance would still exist and retain the timers, making all your events fire twice.

Ideally, you shouldn't have to use this method and the Segment client should be initialized only once in the application lifecycle.

To granularly control when Segment uploads events you can use FlushPolicies. A Flush Policy defines the strategy for deciding when to flush. This can be on an interval, time of day, after receiving a certain number of events, or after receiving a particular event. This gives you more flexibility on when to send event to Segment.

Set Flush Policies in the configuration of the client:

1
const client = createClient({
2
  // ...
3
  flushPolicies: [
4
    new CountFlushPolicy(5),
5
    new TimerFlushPolicy(500),
6
    new StartupFlushPolicy(),
7
  ],
8
});

You can set several policies at a time. When a flush occurs, it triggers an upload of the events, then resets the logic after every flush. As a result, only the first policy to reach shouldFlush triggers a flush. In the example above either the event count reaches 5 or the timer reaches 500ms, whatever comes first, will trigger a flush. Segment has several standard Flush Policies:

• CountFlushPolicy triggers when you reach a certain number of events
• TimerFlushPolicy triggers on an interval of milliseconds
• StartupFlushPolicy triggers on client startup only

Flush policies can be added and removed while the application runs, which lets you adjust the number of flushes as needed.

For example, to disable flushes if you detect the user has no network:

1
import NetInfo from "@react-native-community/netinfo";
2
const policiesIfNetworkIsUp = [
3
  new CountFlushPolicy(5),
4
  new TimerFlushPolicy(500),
5
];
6
// Create our client with our policies by default
7
const client = createClient({
8
  // ...
9
  flushPolicies: [...policiesIfNetworkIsUp],
10
});
11
// If Segment detects the user disconnect from the network, Segment removes all flush policies. 
12
// That way the Segment client won't keep attempting to send events to Segment but will still 
13
// store them for future upload.
14
// If the network comes back up, the Segment client adds the policies back. 
15
const unsubscribe = NetInfo.addEventListener((state) => {
16
  if (state.isConnected) {
17
    client.addFlushPolicy(...policiesIfNetworkIsUp);
18
  } else {
19
    client.removeFlushPolicy(...policiesIfNetworkIsUp)
20
  }
21
});

You can create a custom flush policy by implementing the FlushPolicy interface. You can also extend the FlushPolicyBase class which already creates and handles the shouldFlush value reset.

A FlushPolicy must implement two of the following methods:

• start(): Runs when the flush policy is enabled and added to the client. Use this method to start background operations, make asynchronous calls, or configure settings before execution.
• onEvent(event: SegmentEvent): Runs on every event tracked by your client.
• reset(): Runs after a flush is triggered by your policy, another policy, or manually.

Your policies also have a shouldFlush observable boolean value. When this is set to true, the client attempts to upload events. Each policy should reset this value to false based on its logic, although it's common to do this in the reset method.

1
export class FlushOnScreenEventsPolicy extends FlushPolicyBase {
2
  onEvent(event: SegmentEvent): void {
3
    // Only flush when a screen even happens
4
    if (event.type \
5
    EventType.ScreenEvent) {
6
      this.shouldFlush.value = true;
7
    }
8
  }
9
  reset(): void {
10
    // Superclass will reset the shouldFlush value so that the next screen event triggers a flush again.
11
    // But you can also reset the value whenever, say another event comes in or after a timeout
12
    super.reset();
13
  }
14
}

To avoid sending a Screen event with each navigation action, you can track navigation globally. The implementation depends on which navigation library you use. The two main navigation libraries for React Native are React Navigation and React Native Navigation.

When setting up React Navigation, find the root-level navigation container and call screen() whenever the user navigates to a new screen. Segment's example app is set up with screen tracking using React Navigation, so you can use it as a guide.

To set up automatic screen tracking with React Navigation:

1. Find the file where you used the NavigationContainer. This is the main top-level container for React Navigation.

2. In the component, create a new state variable to store the current route name:

   Copy code block

   const [routeName, setRouteName] = useState('Unknown');

3. Create a utility function for determining the name of the selected route outside of the component:

   Copy code block

   1
     const getActiveRouteName = (
   2
       state: NavigationState | PartialState<NavigationState> | undefined
   3
     ): string => {
   4
       if (!state || typeof state.index !== 'number') {
   5
         return 'Unknown';
   6
       }
   7
   
   8
       const route = state.routes[state.index];
   9
   
   10
       if (route.state) {
   11
         return getActiveRouteName(route.state);
   12
       }
   13
   
   14
       return route.name;
   15
     };

4. Pass a function in the onStateChange prop of your NavigationContainer that checks for the active route name and calls client.screen() if the route has changes. You can pass in any additional screen parameters as the second argument for screen calls as needed.

   Copy code block

   1
   <NavigationContainer
   2
   onStateChange={(state) => {
   3
     const newRouteName = getActiveRouteName(state);
   4
   
   5
     if (routeName !== newRouteName) {
   6
       segmentClient.screen(newRouteName);
   7
       setRouteName(newRouteName);
   8
     }
   9
   }}
   10
   >

To set up automatic screen tracking while using React Native Navigation:

1. Use an event listener at the point where you set up the root of your application, for example, Navigation.setRoot.

2. Access your SegmentClient at the root of your application.

   Copy code block

   1
     // Register the event listener for *registerComponentDidAppearListener*
   2
     Navigation.events().registerComponentDidAppearListener(({ componentName }) => {
   3
       segmentClient.screen(componentName);
   4
     });

Segment's plugin architecture lets you modify and augment how the events are processed before they're uploaded to the Segment API. To customize what happens after an event is created, you can create and place various plugins along the processing pipeline that an event goes through. This pipeline is referred to as a timeline.

Segment is an out-of-the-box DestinationPlugin. You can add as many other destination plugins as you like and upload events and data to them.

If you don't want the Segment destination plugin, set autoAddSegmentDestination = false in the options when setting up your client. This prevents the SegmentDestination plugin from being added automatically.

You can add a plugin at any time using segmentClient.add().

1

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

4
import { AmplitudeSessionPlugin } from '@segment/analytics-react-native-plugin-amplitude';
5
import { FirebasePlugin } from '@segment/analytics-react-native-plugin-firebase';
6
import { IdfaPlugin } from '@segment/analytics-react-native-plugin-idfa';
7

8
const segmentClient = createClient({
9
  writeKey: 'SEGMENT_KEY'
10
});
11

12
segmentClient.add({ plugin: new AmplitudeSessionPlugin() });
13
segmentClient.add({ plugin: new FirebasePlugin() });
14
segmentClient.add({ plugin: new IdfaPlugin() });

Plugins implement as ES6 classes. To get started, familiarize yourself with the available classes in /packages/core/src/plugin.ts.

The available plugin classes are:

• Plugin
• EventPlugin
• DestinationPlugin
• UtilityPlugin
• PlatformPlugin

Any plugin must be an extension of one of these classes. You can then customize the functionality by overriding different methods on the base class. For example, here is a simple Logger plugin:

1
// logger.js
2

3
import {
4
  Plugin,
5
  PluginType,
6
  SegmentEvent,
7
} from '@segment/analytics-react-native';
8

9
export class Logger extends Plugin {
10

11
  // Note that `type` is set as a class property.
12
  // If you do not set a type your plugin will be a `utility` plugin (see Plugin Types above)
13
  type = PluginType.before;
14

15
  execute(event: SegmentEvent) {
16
    console.log(event);
17
    return event;
18
  }
19
}
20
// app.js
21

22
import { Logger } from './logger';
23

24
segmentClient.add({ plugin: new Logger() });

As the plugin overrides execute(), this Logger calls console.log for every event going through the timeline.

You can add custom plugins to destination plugins. For example, you could implement the following logic to send events to Braze on weekends only:

1

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

4
import {BrazePlugin} from '@segment/analytics-react-native-plugin-braze';
5
import {BrazeEventPlugin} from './BrazeEventPlugin';
6

7
const segmentClient = createClient({
8
  writeKey: 'SEGMENT_KEY'
9
});
10

11
const brazeplugin = new BrazePlugin();
12
const myBrazeEventPlugin = new BrazeEventPlugin();
13
brazeplugin.add(myBrazeEventPlugin);
14
segmentClient.add({plugin: brazeplugin});
15

16
// Plugin code for BrazeEventPlugin.ts
17
import {
18
  Plugin,
19
  PluginType,
20
  SegmentEvent,
21
} from '@segment/analytics-react-native';
22

23
export class BrazeEventPlugin extends Plugin {
24
  type = PluginType.before;
25

26
  execute(event: SegmentEvent) {
27
    var today = new Date();
28
    if (today.getDay() === 6 || today.getDay() === 0) {
29
      return event;
30
    }
31
  }
32
}

Segment would then send events to the Braze pestination plugin on Saturdays and Sundays, based on device time.

These are the example plugins you can use and alter to meet your tracking needs:

Use Analytics-React-Native 2.0 to set up destination filters on your mobile device-mode destinations.

To get started with destination filters on mobile device-mode destinations using Analytics-React-Native 2.0:

1. Download and install the @segment/analytics-react-native-plugin-destination-filters package as a dependency in your project.

   • Using NPM:
     Copy code block

     npm install --save @segment/analytics-react-native-plugin-destination-filters

   • Using Yarn:
     Copy code block

     yarn add @segment/analytics-react-native-plugin-destination-filters

2. Follow the instructions for adding plugins on the main Analytics client.

3. Add DestinationFiltersPlugin after you create your Segment client.

   Copy code block

   1
   import { createClient } from '@segment/analytics-react-native';
   2
   
   3
   import { DestinationFiltersPlugin } from '@segment/analytics-react-native-plugin-destination-filters';
   4
   
   5
   const segmentClient = createClient({
   6
     writeKey: 'SEGMENT_KEY'
   7
   });
   8
   
   9
   segmentClient.add({ plugin: new DestinationFiltersPlugin() });
   10
   segment.add({ plugin: new FirebasePlugin() })

Segment supports a large number of cloud-mode destinations. Segment also supports the following destinations for Analytics React Native 2.0 in device-mode:

• Adjust
• Amplitude Session
• Appsflyer
• Braze
• CleverTap
• Facebook App Events
• Firebase

On Android, Segment's React Native library generates a unique ID by using the DRM API as context.device.id. Some destinations rely on this field being the Android ID, so be sure to double-check the destination's vendor documentation. If you choose to override the default value using a plugin, make sure the identifier you choose complies with Google's User Data Policy. For iOS, the context.device.id is set to the IDFV.

To collect the Android Advertising ID provided by Play Services, Segment provides a plugin that can be used to collect that value. This value is set to context.device.advertisingId. For iOS, this plugin can be used to set the IDFA context.device.advertisingId property.

Find answers to common Analytics React Native questions.

No, only the plugins listed are supported in device-mode for Analytics React Native 2.0.

When you successfully package a plugin in device-mode, you won't see the integration listed as false in the integrations object for a Segment event. This logic is packaged in the event metadata, and isn't surfaced in the Segment debugger.

Due to limitations with the React Native bridge, Segment doesn't use UUID format for anonymousId and messageId values in local development. These IDs will be set in UUID format for your live app.

You can set different writeKeys for iOS and Android. This is useful if you want to send data to different destinations based on the client side platform. To set different writeKeys, you can dynamically set the writeKey when you initialize the Segment client:

1
import {Platform} from 'react-native';
2
import { createClient } from '@segment/analytics-react-native';
3

4
const segmentWriteKey = Platform.iOS ? 'ios-writekey' : 'android-writekey';
5

6
const segmentClient = createClient({
7
  writeKey: segmentWriteKey
8
});

The instanceId was introduced in v2.10.1 and correlates events to a particular instance of the client in a scenario when you might have multiple instances on a single app.

The Integrations object is no longer part of the Segment events method signature. To access the Integrations object and control what destinations the event reaches, you can use a plugin:

1
import {
2
    EventType,
3
    Plugin,
4
    PluginType,
5
    SegmentEvent,
6
  } from '@segment/analytics-react-native';
7
  
8
  export class Modify extends Plugin {
9
    type = PluginType.before;
10
  
11
    async execute(event: SegmentEvent) {
12
      if (event.type == EventType.TrackEvent) {
13
        let integrations = event.integrations;
14
        if (integrations !== undefined) {
15
          integrations['Appboy'] = false;
16
        }
17
      }
18
      //console.log(event);
19
      return event;
20
    }
21
  }

You need to use a plugin to access and modify the Context object. For example, to add context.groupId to every Track call, create a plugin like this:

1
//in AddToContextPlugin.js
2
import {
3
  Plugin,
4
  PluginType,
5
  SegmentEvent,
6
} from '@segment/analytics-react-native';
7

8
export class AddToContextPlugin extends Plugin {
9
  // Note that `type` is set as a class property
10
  // If you do not set a type your plugin will be a `utility` plugin (see Plugin Types above)
11
  type = PluginType.enrichment;
12

13
 async execute(event: SegmentEvent) {
14
    if (event.type == EventType.TrackEvent) {
15
      event.context['groupId'] = 'test - 6/8'
16
      }
17
      return event;
18
    }
19
}
20
 // in App.js
21

22
import { AddToContextPlugin } from './AddToContextPlugin'
23

24
segmentClient.add({ plugin: new AddToContextPlugin() });  

The React Native 2.0 library is compliant with Google Play Store policies. However, Segment recommends that you check to see if there are any old and inactive tracks on the Google Play Store that are not updated to the latest build. If this is the case, Segment recommends updating those tracks to resolve the issue.

Segment requires the inlineRequires value in your metro.config.js value to be set to true. To disable inlineRequires for certain modules, you can specify this using a blockList.

The Reset method on userInfo can accept a function that receives the current state and returns a modified desired state. Using this method, you can return the current traits, delete any traits you no longer wish to track, and persist the new trait set.

1
segmentClient.userInfo.set((currentUserInfo) => {
2
  return {
3
    ...currentUserInfo, 
4
    traits: {
5
        // All the traits except the one you want to delete
6
       persistentTrait: currentUserInfo.persistentTrait
7
    }
8
  });

If you proxy your events through the proxy config option, you must forward the batched events to https://api.segment.io/v1/b. The https://api.segment.io/v1/batch endpoint is reserved for events arriving from server-side sending. Proxying to that endpoint for your mobile events may result in unexpected behavior.

View the Analytics React Native changelog on GitHub.