RudderStack React Native SDK

Detailed technical documentation on RudderStack’s React Native SDK to send events from your React Native application to various destinations.

What is the RudderStack React Native SDK?

The RudderStack React Native SDK allows you to track event data from your app. It can be easily integrated into your React Native application. After integrating this SDK, you will also be able to send the event data to your preferred analytics destination/s such as Google Analytics, Amplitude, and more.

You can check the GitHub codebase if you want to get more hands-on or are keen to know the SDK architecture.

SDK Setup Requirements

To set up the RudderStack React Native SDK, there are a few prerequisites as mentioned below:

  • You will need to set up a RudderStack Account.

  • Once signed up, your React Native source writeKey will appear in the Dashboard, as shown:

Adding React Native SDK
  • You will also need your Data-Plane URL. The following screenshot shows the data plane URL for the managed hosting mode:

Data Plane URL

Installing the RudderStack React Native SDK

The recommended way to install the React Native SDK is through npm.

To add the SDK as a dependency, perform the following steps:

  • Go to the root of your Application and add @rudderstack/rudder-sdk-react-native to your Application as a dependency with:

npm
yarn
npm
npm install @rudderstack/rudder-sdk-react-native --save
yarn
yarn add @rudderstack/rudder-sdk-react-native
  • Navigate to your Application's Android folder and add the following to your application's build.gradle file:

maven {
url { "https://dl.bintray.com/rudderstack/rudderstack" }
}
  • Navigate to your Application's iOS folder and install all the required pods with:

pod install

Initializing the RudderStack Client

After adding the SDK as a dependency, you need to setup the SDK.

  • Make sure to import the SDK wherever you use it with:

import rudderClient from '@rudderstack/rudder-sdk-react-native'
  • Add the following code somewhere in your application.

await rudderClient.setup( <YOUR_WRITE_KEY>, {
dataPlaneUrl: <DATA_PLANE_URL>,
recordScreenViews: true
})

It is highly recommended to use the await keyword with the setup call.

The setup method has the following signature:

Name

Data Type

Required

Description

writeKey

string

Yes

Your React Native writeKey

configuration

JSON Object

No

Contains the RudderStack Client configuration

Check the Configuring your RudderStack Client section below for a full list of configurable parameters.

Track

You can record the users' activity through the track method. Every action performed by the user is called an event.

An example of the track event is as shown:

rudderClient.track("test_track_event", {
"test_key_1": "test_value_1",
"test_key_2": {
"test_child_key_1":"test_child_value_1"
}
})

The track method has the following signature:

Name

Data Type

Required

Description

name

string

Yes

Name of the event you want to track

property

JSON Object

No

Extra data properties you want to send along with the event

options

JSON Object

No

Extra event options

We automatically track the following optional events:

  1. Application Installed

  2. Application Updated

  3. Application Opened

  4. Application Backgrounded

You can disable these events by passing trackLifecycleEvents as false in the configuration object. But it is highly recommended to keep them enabled.

Identify

Capture deviceId and use that as anonymousId for identifying the user. It helps to track the users across the application installation. To attach more information to the user, you can use the identify method. Once you set the identify information to the user, those will be passed to the successive track or screen calls. To reset the user identification, you can use the reset method.

An example identify event is as shown:

rudderClient.identify("test_userId", {
"email":"testuser@example.com",
"location":"UK"
}, null)

The identify method has the following signatures:

Name

Data Type

Required

Description

userId

string

Yes

Developer identity for the user

traits

JSON Object

No

Traits information for user

option

JSON Object

No

Extra options for the identify event

Screen

You can use the screen call to record whenever the user sees a screen on the mobile device. You can also send some extra properties along with this event.

An example of the screen event is as shown:

rudderClient.screen("Main Activity", {
"foo":"bar"
})

Alternatively, you can use the following method signature:

Name

Data Type

Required

Description

screenName

string

Yes

Name of the screen viewed.

property

JSON Object

No

Extra property object that you want to pass along with the screen call.

option

JSON Object

No

Extra options to be passed along with screen event.

You can also enable automatic recording of screen views by passing recordScreenViews as true while initializing the rudderClient. The default value for recordScreenViews is false.

Reset

You can use the reset method to clear the persisted traits for the identify call. This is required for Logout operations.

await rudderClient.reset()

It is highly recommended to use the await keyword with the reset call.

Configuring your RudderStack Client

You can configure your client based on the following parameters by passing them in the configuration object of your setup call.

Parameter

Type

Description

Default Value

logLevel

int

Controls how much of the log you want to see from the SDK.

Refer to the Debugging section to a get a list of all supported values.

RUDDER_LOG_LEVEL.ERROR

dataPlaneUrl

string

URL of your data-plane. Please refer above to see how to fetch the data plane URL.

https://hosted.rudderlabs.com

flushQueueSize

int

Number of events in a batch request to the server.

30

dbThresholdCount

int

Number of events to be saved in the SQLite database. Once the limit is reached, older events are deleted from the DB.

10000

sleepTimeout

int

Minimum waiting time to flush the events to the server.

10 seconds

configRefreshInterval

int

It will fetch the config from dashboard after this many hours.

2

trackLifecycleEvents

boolean

Whether SDK will capture application life cycle events automatically.

true

recordScreenViews

boolean

Whether SDK will capture screen view events automatically.

false

controlPlaneUrl

string

If you are using our open-source config generator, use this option to point to your hosted sourceConfig. SDK will add /sourceConfig along with this URL

https://api.rudderlabs.com

Debugging

If you run into any issues regarding the RudderStack React Native SDK, you can turn on the VERBOSE or DEBUG logging to find out what the issue is.

First, make sure you modify your import statement to include RUDDER_LOG_LEVEL with:

import rudderClient, { RUDDER_LOG_LEVEL } from '@rudderstack/rudder-sdk-react-native'

Then to turn on the logging, change your RudderClient initialisation to the following:

await rudderClient.setup( <YOUR_WRITE_KEY>, {
dataPlaneUrl: <DATA_PLANE_URL>,
logLevel: RUDDER_LOG_LEVEL.DEBUG // or VERBOSE
})

You can set the log level to one of the following values:

  1. NONE

  2. ERROR

  3. WARN

  4. INFO

  5. DEBUG

  6. VERBOSE

FAQ

No, you don't need to link the SDK as it is auto-linked.If you have linked it using react-native link and are facing issues, use react-native unlink rudder-sdk-react-native to un-link it.

Can I use the SDK with a React Native application created with Expo?

No.The SDK is a React Native module and currently expo doesn't support adding native modules.You can still eject your Expo application and use our Android and iOS SDKs.

What is the need to use the await keyword?

The functions exposed by the SDK are asynchronous in nature.If you want synchronous behavior, you must use the await keyword.We highly recommend using the await keyword with the setup call as it would make sure that the SDK has been properly setup before any further calls are made.

Android build fails after adding the SDK to your Application?

Please try using Android Studio to build your application, this should fix most of the errors.

Contact us

In case of any queries, you can always reach out to us, or feel free to open an issue on our GitHub Issues page in case of any discrepancy.