Analytics for React Native 2.0
React Native 2.0 is a major version upgrade to the existing React Native library that is production-ready. With Analytics for React Native 2.0, you can collect analytics in your React Native application and send data to any analytics or marketing tool without having to learn, test, or implement a new API every time. Analytics React Native 2.0 enables you to process and track the history of a payload, while Segment controls the API and prevents unintended operations.
All of Segment’s libraries are open-source, and you can view Analytics for React Native 2.0 on GitHub. For more information, see the Analytics React Native 2.0 GitHub repository.
Using Analytics for React Native Classic?
If you’re still using the classic version of Analytics for React Native, you can refer to the documentation here.
On May 15, 2023, Segment will end support for Analytics React Native Classic, which includes versions 1.5.1 and older. Upgrade to Analytics React Native 2.0. See the Analytics React Native 2.0 docs to learn more.
Upgrade to Analytics React Native 2.0. See the Analytics React Native 2.0 docs to learn more.
If you’re migrating to Analytics React Native 2.0 from an older Analytics React Native version, skip to the migration guide.
@segment/analytics-react-native 2.0
is compatible with Expo’s Custom Dev Client and EAS builds without any additional configuration. Destination Plugins that require native modules may require custom Expo Config Plugins.
@segment/analytics-react-native 2.0
isn’t compatible with Expo Go.
Getting Started
To get started with the Analytics for React Native 2.0 library:
- Create a React Native Source in Segment.
- Go to Connections > Sources > Add Source.
- Search for React Native and click Add source.
-
Install
@segment/analytics-react-native
,@segment/sovran-react-native
andreact-native-async-storage/async-storage
:yarn add @segment/analytics-react-native @segment/sovran-react-native @react-native-async-storage/async-storage # or npm install --save @segment/analytics-react-native @segment/sovran-react-native @react-native-async-storage/async-storage
-
If you’re using iOS, install native modules with:
npx pod-install
-
If you’re using Android, you need to add extra permissions to your
AndroidManifest.xml
. Add the line below between the `` tags:<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
-
Initialize and configure the Analytics React Native 2.0 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.import { createClient, AnalyticsProvider } from '@segment/analytics-react-native'; const segmentClient = createClient({ writeKey: 'SEGMENT_API_KEY' });
These are the options you can apply to configure the client:
Option Name Description writeKey
requiredThis is your Segment write key. autoAddSegmentDestination
The default is set to true
.
This automatically adds the Segment Destination plugin. Set tofalse
if you don’t want to add the Segment Destination.debug
The default is set to true
.
The default value isfalse
in production.
When set to false, logs don’t generate.defaultSettings
The default is set to undefined
.
Settings that will be used if the request to get the settings from Segment fails.flushAt
The default is set to 20
.
The count of events at which Segment sends to the backend.flushInterval
The default is set to 30
.
The interval in seconds at which Segment sends events to the backend.maxBatchSize
The default is set to 1000
.
The maxiumum batch size of how many events to send to the API at once.trackAppLifecycleEvents
The default is set to false
.
This enables you to automatically track app lifecycle events, such as application installed, opened, updated, backgrounded. Set to true totrue
to track.trackDeepLinks
The default is set to false
.
This automatically tracks when the user opens the app via a deep link. Set to Enable automatic tracking for when the user opens the app via a deep link.proxy
The default is set to undefined
.
This is a batch url to post to instead of the default batch endpoint.collectDeviceId
The default is set to fasle
.
This automatically adds adevice.Id
property to the context object from the DRM API on Android devices.
Set up iOS Deep Link Tracking
This is only required for iOS if you’re using the trackDeepLinks
option. Android doesn’t require any additional setup.
To track deep links in iOS, add the following to your AppDelegate.m
file:
- (BOOL)application:(UIApplication *)application
openURL: (NSURL *)url
options:(nonnull NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
[AnalyticsReactNative trackDeepLink:url withOptions:options];
return YES;
}
Usage
See how to use Analytics React Native 2.0 with hooks or without hooks.
Usage with 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.
import {
createClient,
AnalyticsProvider,
} from '@segment/analytics-react-native';
const segmentClient = createClient({
writeKey: 'SEGMENT_API_KEY'
});
const App = () => (
<AnalyticsProvider client={segmentClient}>
<Content />
</AnalyticsProvider>
);
The useAnalytics()
hook exposes the client methods:
import React from 'react';
import { Text, TouchableOpacity } from 'react-native';
import { useAnalytics } from '@segment/analytics-react-native';
const Button = () => {
const { track } = useAnalytics();
return (
<TouchableOpacity
style={styles.button}
onPress={() => {
track('Awesome event');
}}
>
<Text style={styles.text}>Press me!</Text>
</TouchableOpacity>
);
};
Usage without hooks
To use the tracking events without hooks, call the methods directly on the client:
import {
createClient,
AnalyticsProvider,
} from '@segment/analytics-react-native';
// create the client once when the app loads
const segmentClient = createClient({
writeKey: 'SEGMENT_API_KEY'
});
// track an event using the client instance
segmentClient.track('Awesome event');
Tracking Methods
Once you’ve installed the Analytics React Native 2.0 library, you can start collecting data through Segment’s tracking methods:
- Identify
- Track
- Screen
- Group
Identify
The Identify method lets you tie a user to their actions and record traits about them. This includes a unique user ID and any optional traits you know about them like their email, name, or address. The traits option can include any information you want to tie to the user. When using any of the reserved user traits, be sure the information reflects the name of the trait. For example, email
should always be a string of the user’s email address.
identify: (userId: string, userTraits?: JsonMap) => void;
const { identify } = useAnalytics();
identify('user-123', {
username: 'MisterWhiskers',
email: 'hello@test.com',
plan: 'premium',
});
Track
The Track method lets you record the actions your users perform. Every action triggers an event, which also has associated properties that the track method records.
track: (event: string, properties?: JsonMap) => void;
const { track } = useAnalytics();
track('View Product', {
productId: 123,
productName: 'Striped trousers',
});
Screen
The Screen method lets you record whenever a user sees a screen in your mobile app, along with optional extra information about the page being viewed.
You’ll want to record a screen event whenever the user opens a screen in your app. This could be a view, fragment, dialog, or activity depending on your app.
Not all integrations support screen, so when it’s not supported explicitly, the screen method tracks as an event with the same parameters.
screen: (name: string, properties?: JsonMap) => void;
const { screen } = useAnalytics();
screen('ScreenName', {
productSlug: 'example-product-123',
});
For setting up automatic screen tracking, see the Automatic Screen Tracking instructions.
Group
The Group method lets you associate an individual user with a group— whether it’s a company, organization, account, project, or team. This includes a unique group identifier and any additional group traits you may know, like company name, industry, or number of employees. You can include any information you want to associate with the group in the traits option. When using any of the reserved group traits, be sure the information reflects the name of the trait. For example, email should always be a string of the user’s email address.
group: (groupId: string, groupTraits?: JsonMap) => void;
const { group } = useAnalytics();
group('some-company', {
name: 'Segment',
});
Utility Methods
The Analytics React Native 2.0 utility methods help you to manage your data. They include:
- Alias
- Reset
- Flush
- Cleanup
Alias
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;
const { alias } = useAnalytics();
alias('user-123');
Reset
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.
Note: Each time you call reset, a new AnonymousId is generated automatically.
reset: () => void;
const { reset } = useAnalytics();
reset();
Flush
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>;
const { flush } = useAnalytics();
flush();
Cleanup
In case you need to reinitialize the client, that is, 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.
let client = createClient({
writeKey: 'KEY'
});
client.cleanup();
client = createClient({
writeKey: 'KEY'
});
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.
Automatic screen tracking
As sending a screen() event with each navigation action can get tiresome, it’s best to track navigation globally. The implementation is different depending on which library you use for navigation. The two main navigation libraries for React Native are React Navigation and React Native Navigation.
React Navigation
When setting up React Navigation, you’ll essentially 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:
- Find the file where you used the
NavigationContainer
. This is the main top level container for React Navigation. -
In the component, create a new state variable to store the current route name:
const [routeName, setRouteName] = useState('Unknown');
-
Create a utility function for determining the name of the selected route outside of the component:
const getActiveRouteName = ( state: NavigationState | PartialState<NavigationState> | undefined ): string => { if (!state || typeof state.index !== 'number') { return 'Unknown'; } const route = state.routes[state.index]; if (route.state) { return getActiveRouteName(route.state); } return route.name; };
-
Pass a function in the
onStateChange
prop of yourNavigationContainer
that checks for the active route name and callsclient.screen()
if the route has changes. You can pass in any additional screen parameters as the second argument for screen calls as needed.<NavigationContainer onStateChange={(state) => { const newRouteName = getActiveRouteName(state); if (routeName !== newRouteName) { segmentClient.screen(newRouteName); setRouteName(newRouteName); } }} >
React Native Navigation
In order to set up automatic screen tracking while using React Native Navigation:
- Use an event listener at the point where you set up the root of your application (for example,
Navigation.setRoot
). -
Access your
SegmentClient
at the root of your application.// Register the event listener for *registerComponentDidAppearListener* Navigation.events().registerComponentDidAppearListener(({ componentName }) => { segmentClient.screen(componentName); });
Plugin Architecture
Segment’s plugin architecture enables you to modify and augment how the events are processed before they’re uploaded to the Segment API. In order 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.
Plugin Types
Plugin Type | Description |
---|---|
before |
Executes before event processing begins. |
enrichment |
Executes as the first level of event processing. |
destination |
Executes as events begin to pass off to destinations. |
after |
Executes after all event processing is completed. You can use this to perform cleanup operations. |
utility |
Executes only with manual calls such as Logging. |
Plugins can have their own native code (such as the iOS-only IdfaPlugin
or wrap an underlying library (such as the FirebasePlugin
which uses react-native-firebase
under the hood).
Destination Plugins
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, you can pass autoAddSegmentDestination = false
in the options when setting up your client. This prevents the SegmentDestination
plugin from being added automatically for you.
Adding Plugins
You can add a plugin at any time through the segmentClient.add()
method.
import { createClient } from '@segment/analytics-react-native';
import { AmplitudeSessionPlugin } from '@segment/analytics-react-native-plugin-amplitude';
import { FirebasePlugin } from '@segment/analytics-react-native-plugin-firebase';
import { IdfaPlugin } from '@segment/analytics-react-native-plugin-idfa';
const segmentClient = createClient({
writeKey: 'SEGMENT_KEY'
});
segmentClient.add({ plugin: new AmplitudeSessionPlugin() });
segmentClient.add({ plugin: new FirebasePlugin() });
segmentClient.add({ plugin: new IdfaPlugin() });
Writing your own Plugins
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:
// logger.js
import {
Plugin,
PluginType,
SegmentEvent,
} from '@segment/analytics-react-native';
export class Logger extends Plugin {
// Note that `type` is set as a class property
// If you do not set a type your plugin will be a `utility` plugin (see Plugin Types above)
type = PluginType.before;
execute(event: SegmentEvent) {
console.log(event);
return event;
}
}
// app.js
import { Logger } from './logger';
segmentClient.add({ plugin: new Logger() });
As the plugin overrides the execute()
method, this Logger
calls console.log
for every event going through the Timeline.
Add a custom Destination Plugin
You can add custom plugins to Destination Plugins. For example, you could implement the following logic to send events to Braze on weekends only:
import { createClient } from '@segment/analytics-react-native';
import {BrazePlugin} from '@segment/analytics-react-native-plugin-braze';
import {BrazeEventPlugin} from './BrazeEventPlugin';
const segmentClient = createClient({
writeKey: 'SEGMENT_KEY'
});
const brazeplugin = new BrazePlugin();
const myBrazeEventPlugin = new BrazeEventPlugin();
brazeplugin.add(myBrazeEventPlugin);
segmentClient.add({plugin: brazeplugin});
// Plugin code for BrazeEventPlugin.ts
import {
Plugin,
PluginType,
SegmentEvent,
} from '@segment/analytics-react-native';
export class BrazeEventPlugin extends Plugin {
type = PluginType.before;
execute(event: SegmentEvent) {
var today = new Date();
if (today.getDay() === 6 || today.getDay() === 0) {
return event;
}
}
}
Segment would then send events to the Braze Destination Plugin on Saturdays and Sundays, based on device time.
Example Plugins
These are the example plugins you can use and alter to meet your tracking needs:
Plugin | Package |
---|---|
Adjust | @segment/analytics-react-native-plugin-adjust |
Amplitude Sessions | @segment/analytics-react-native-plugin-amplitude-session |
AppsFlyer | @segment/analytics-react-native-plugin-appsflyer |
Braze | @segment/analytics-react-native-plugin-braze |
Consent Manager | @segment/analytics-react-native-plugin-adjust |
Facebook App Events | @segment/analytics-react-native-plugin-facebook-app-events |
Firebase | @segment/analytics-react-native-plugin-consent-firebase |
IDFA | @segment/analytics-react-native-plugin-idfa |
Supported Destinations
Segment supports a large number of Cloud-mode destinations. Segment also supports the below destinations for Analytics React Native 2.0 in device-mode, with more to follow:
Device identifiers
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 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.
FAQs
Can I use the catalog of device-mode destinations from Segment’s 1.X.X React-Native release?
No, only the plugins listed above are supported in device-mode for Analytics React Native 2.0.
Will I still see device-mode integrations listed as false
in the integrations object?
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.
Why are my IDs not set in UUID format?
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.
How do I set a distinct writeKey for iOS and android?
You can set different writeKeys for iOS and Android. This is helpful 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:
import {Platform} from 'react-native';
import { createClient } from '@segment/analytics-react-native';
const segmentWriteKey = Platform.iOS ? 'ios-writekey' : 'android-writekey';
const segmentClient = createClient({
writeKey: segmentWriteKey
});
Changelog
This page was last modified: 14 Mar 2023
Need support?
Questions? Problems? Need more info? Contact Segment Support for assistance!