Skip to content

rudderstack-react-native-sdk.md

Latest commit

 

History

History
372 lines (282 loc) · 13.2 KB

rudderstack-react-native-sdk.md

File metadata and controls

372 lines (282 loc) · 13.2 KB
description Detailed technical documentation on RudderStack’s React Native SDK to send events from your React Native application to various destinations.

React Native

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 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 keen to know more about 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:

{% tabs %} {% tab title="npm" %}

npm install @rudderstack/rudder-sdk-react-native --save

{% endtab %}

{% tab title="yarn" %}

yarn add @rudderstack/rudder-sdk-react-native

{% endtab %} {% endtabs %}

  • 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 set up 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( WRITE_KEY, {
    dataPlaneUrl: DATA_PLANE_URL,
    trackLifecycleEvents: true,
    recordScreenViews: true
})

{% hint style="success" %} It is highly recommended to use the await keyword with the setup call. {% endhint %}

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

{% hint style="info" %} 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. {% endhint %}

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.

{% hint style="info" %} 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. {% endhint %}

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()

{% hint style="success" %} It is highly recommended to use the await keyword with the reset call. {% endhint %}

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 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 The 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 initialization to the following:

await rudderClient.setup(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

Advertising ID

You can use the setAdvertisingId method to pass your Android and iOS AAID and IDFA respectively. The setAdvertisingId method accepts two string arguments :

  • androidId : Your Android advertisingId (AAID)
  • iOSId : Your iOS advertisingId (IDFA)

Example Usage:

rudderClient.setAdvertisingId(AAID, IDFA);

Anonymous ID

You can use the setAnonymousId method to pass your anonymousId and the SDK will use that instead of the deviceId. The setAnonymousId method accepts one string argument:

  • id : Your anonymousId

An example of this method's usage is as shown:

rudderClient.setAnonymousId(ANONYMOUS_ID);

FAQ

Do I need to link the SDK using the React Native link?

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 unlink it.

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

No. The SDK is a React Native module, and currently, the 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 to make sure that the SDK has been properly set up before any further calls are made.

Does 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 contact us, or feel free to open an issue on our GitHub Issues page in case of any discrepancy. You can also start a conversation on our Slack channel; we will be happy to talk to you!