MIGRATION_GUIDE.md

Migrating to 2.0

Analytics-React-Native 2.0 currently supports these destinations with Segment actively adding more to the list. If you’re using analytics-react-native 1.5.1 or older, follow these steps to migrate to the analytics-react-native 2.0. You can continue to use your React Native source write key for the migration to view historical events.

---

🚨 Important Note: Analytics React Native 2.0 implements a new storage framework, @segment/sovran-react-native, which makes it impossible to determine if your app has been previously installed.

Migrating to Analytics React Native 2.0 results in new Application Installed events for your existing users. To filter these events out you can either create an Enrichment Plugin to drop events or filter them using your Segment workspace.

---

1. Update existing package

yarn upgrade @segment/analytics-react-native

If you are using any device mode destinations from V1 you will have to remove them and add their equivalent plugin package for V2.

2. Add/Update pods

npx pod-install

3. Add permission to AndroidManifest.xml

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

Client Configuration

You will have to remove your current configuration and replace it with the createClient method. For more information, reference Setting up the client.

Example client configuration for analytics-react-native 1.5.1

App.js:

import analytics from '@segment/analytics-react-native'

...

analytics.setup('WRITE_KEY', {
 debug: true,
 using: [amplitude, appsflyer],
 trackAdvertising: true,
});

package.json

"dependencies": {
   ...
  "@segment/analytics-react-native": "1.5.1"
 }

podfile.lock

PODS:
...
 - Analytics (4.1.6)
}

Example client configuration for analytics-react-native 2.0.0 App.tsx (or .js):

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

...

const segmentClient = createClient({
 writeKey: 'WRITE_KEY',
 trackAppLifecycleEvents: true,
});

const App = () => {
 ...
 return (
   <AnalyticsProvider client={segmentClient}>
    ...
   </AnalyticsProvider>
  );
};

package.json

"dependencies": {
  ...
 "@react-native-async-storage/async-storage": "^1.15.11",
 "@segment/analytics-react-native": "2.0.0"
}

podfile.lock

PODS:
...
- segment-analytics-react-native (2.0.0):
 - React-Core
}

Tracking Implementation

Example tracking implementation for analytics-react-native 1.5.1

Home.js

import analytics from '@segment/analytics-react-native';

...

import analytics from '@segment/analytics-react-native';
...
onSendEvent = async() => {
 let name = this.state.eventName
 let properties = this.state.props

 await analytics.track(name, properties);
}

Example tracking implementation for analytics-react-native 2.0.0

Home.tsx

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

...

const Home = ({ navigation }: { navigation: any }) => {
  const { screen, track, identify, group, alias, reset, flush } =
    useAnalytics();
    ...
 onPress: () => {
  track('Track pressed', { foo: 'bar' });
 };
 ...
};

Plugins

The plugins for V2 have changed from V1.

The plugins have been re-released with different names. These are the equivalent packages for V2. Not all packages in V1 have yet been released for V2 but Segment is actively adding more packages to the list.

Also review the main package list for new V2 plugins.

Plugin	V1 Package	V2 Package
Adjust	@segment/analytics-react-native-adjust	@segment/analytics-react-native-plugin-adjust
Amplitude Sessions	@segment/analytics-react-native-amplitude	@segment/analytics-react-native-plugin-amplitude-session
AppsFlyer	@segment/analytics-react-native-appsflyer	@segment/analytics-react-native-plugin-appsflyer
Facebook App Events	@segment/analytics-react-native-facebook-app-events-ios	@segment/analytics-react-native-plugin-facebook-app-events
Firebase	@segment/analytics-react-native-firebase	@segment/analytics-react-native-plugin-firebase
Mixpanel	@segment/analytics-react-native-mixpanel	@segment/analytics-react-native-plugin-mixpanel
Taplytics	@segment/analytics-react-native-taplytics-ios	@taplytics/segment-react-native-plugin-taplytics

Context Traits

Previous versions of this library used to persist traits in context.traits across all event types after an identify event was sent. We no longer not support this out of the box in V2 as well as the rest of our mobile libraries due to concerns of data privacy for some device mode destinations. Some device mode destinations might not accept events if they contain identifiable data as it is against their Terms of Service.

If you need to keep this behavior, we have an example plugin InjectTraits that you can use for it. This plugin injects the current user traits into context.traits of every event.

To use it, copy the file into your codebase and add it into your client:

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

import { InjectTraits } from './InjectTraits';

const segmentClient = createClient({
  writeKey: 'SEGMENT_KEY'
});

segmentClient.add({ plugin: new InjectTraits() });

Please note that as this is an example we don't offer full support for it and will not release it as an NPM package.