Please reach out to MetaRouter before testing or implementing this library.

Overview

This library lets you record analytics data from your React Native app's code. Once installed, the requests will be sent to the MetaRouter platform and then sent to the integrations you have configured for your pipeline that is connected to your React Native events. The library is built for high performance and uses and internal queue to make all calls non-blocking and fast. It will batch messages and flush asynchronously to the MetaRouter platform.

iOS CocoaPods

First, add CocoaPods to your app. Follow these instructions.

Installing and configuring the SDK

The recommended way to install Analytics for React Native is via npm, since it means you can create a build with specific integrations and because it makes it relatively simple to install and upgrade.

First, add the @metarouter/analytics-react-native dependency to your dependencies and link it using react-native-cli:

yarn add @metarouter/analytics-react-native
yarn react-native link

Then change the current directory to ios:

cd ios

Next, run pod install to install the required dependences for iOS.

Then, somewhere your application, setup the SDK:

await analytics.setup('YOUR_WRITE_KEY', {
  // Record screen views automatically!
  recordScreenViews: true,
  // Record certain application events automatically!
  trackAppLifecycleEvents: true,
})

Finally, import the SDK in the files that you use it with:

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

Required SDK Edits

Your writeKey will indicate the specific pipeline you would like to feed your events into.

Event Methods in React Native

Check out the below event methods and their use cases to determine the events that you need to trigger. We have also included examples of how you can call specific objects with React Native. More information on event methods can be found here.

Identify Your Users

The identify method helps you associate your users and their actions to a unique and recognizable userID and any optional traits that you know about them. We recommend calling an identify a single time - when the user's account is first created and only again when their traits change.

Note: Users are automatically assigned an anonymousID before you identify them. The userID is then what connects anonymous activity across mobile iOS devices.

A simple identify event call looks something like this:

analytics.identify("1234qwerty", {
  email: "user's email address",
})

This call identifies a user by his unique User ID (the one you know him by in your database) and labels him with name and email traits.

Note: When you add an identify to your React Native app, you will need to replace all those hard-coded strings with details about the currently logged-in user.

Analytics works on its own background thread, so it will never block the main thread for the UI or the calling thread.

Calling identify with a userId will write that ID to disk to be used in subsequent calls. That ID can be removed either by uninstalling the app or by calling reset.

Track

To get to a more complete event tracking analytics setup, you can add a track call to your app. This will tell MetaRouter which actions users are performing in your app. With track, each user action triggers an event, which can also have associated properties.

The React Native SDK can automatically track a few common events (e.g. Application_Installed, Application_Opened, and Application_Updated). During initialization, automatically tracking these events is set to true by default, but you can change this to false if you would rather not track these events automatically. In addition to these lifecycle events, you will likely want to track some events that are success indicators for your app - like Viewed Product, Email Sign Up, Item Purchased, etc.

Below is a sample React Native track event.

analytics.track('Item Purchased', {
  item: 'Cat Feather Toy',
  revenue: 9.99,
})

Screen

The screen method lets you you record whenever a user sees a screen of your mobile app, along with optional extra information about the page being viewed. You will 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.

Example screen call:

analytics.screen('Photo Feed', {
  'Feed Type': 'private',
})

Group

A Group event lets you associate an identified user user with a group. A group could be a company, organization, account, project or team. It also lets you record custom traits about the group, like industry or number of employees.

Example group call:

analytics.group('group123', {
  name: 'Initech',
  description: 'Accounting Software',
})

Reset

The reset method clears the SDK’s internal stores for the current user and group. This is useful for apps where users can log in and out with different identities over time.

Clearing all information about the user can be performed by calling:

analytics.reset()

Flushing

You can specify the number of events that should queue before flushing. Set this to 1 to send events as they come in (i.e. streamed, not batched). Note that this will use more battery on the user's device. This setting is set to 20 by default.

await analytics.setup('YOUR_WRITE_KEY', {
  flushAt: 1,
})

Native Configuration

You can also use the native Analytics API to configure the React Native library. Just make sure to call analytics.useNativeConfiguration() in your JavaScript code so Analytics doesn’t wait for you to configure it.

Application Lifecycle Tracking

As mentioned previously, the React Native SDK can automatically instrument common application lifecycle events such as Application Installed, Application Updated and Application Opened. Simply enable this option when you initialize the SDK. Within the initialization step, ensure that trackAppLifecycleEvents is set to true.

Logging

To see a trace of your data going through the SDK, you can enable debug logging with the debug method:

await analytics.setup('YOUR_WRITE_KEY', {
  debug: true,
})

By default, debug logging is disabled.

Submitting to the iOS App Store

When submitting to the iOS App Store, beware that MetaRouter collects the IDFA for use in performing mobile install attribution. Even if you are not currently utilizing mobile install attribution, if you get asked, “Does this app use the Advertising Identifier (IDFA)?” on this page, you will want to check the following three boxes:

"Attribute this app to a previously sent advertisement"
“Attribute an action taken within this app to a previously served advertisement”
“I, YOUR_NAME, confirm that this app, and any third party…”

Unless you plan to display ads within your app, do not check the box labeled "Serve advertisements within the app".