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

• It would help if you also had the React Native Development Environment setup on your system.

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:

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

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

• Navigate to your Application's iOS folder and install all the required pods with:

Copy
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:

Copy
import rudderClient from "@rudderstack/rudder-sdk-react-native"

• Add the following code somewhere in your application.

Copy
await rudderClient.setup(WRITE_KEY, {
  dataPlaneUrl: DATA_PLANE_URL,
  trackLifecycleEvents: true,
  recordScreenViews: true,
})

The setup method has the following signature:

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:

Copy
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:

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:

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

The identify method has the following signatures:

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:

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

Alternatively, you can use the following method signature:

Reset

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

Copy
await rudderClient.reset()

Enabling/Disabling User Tracking via the optOut API (GDPR Support)

RudderStack gives the users (e.g., an EU user) the ability to opt out of tracking any user activity until the user gives their consent. You can do this by leveraging RudderStack's optOut API.

The optOut API takes true or false as a Boolean value to enable or disable tracking user activities. This flag persists across device reboots.

The following snippet highlights the use of the optOut API to disable user tracking:

Copy
await rudderClient.optOut(true)

Once the user grants their consent, you can enable user tracking once again by using the optOut API with false as a parameter sent to it, as shown:

Copy
await rudderClient.optOut(false)

Registering Callbacks:

The React Native SDK lets you trigger a callback once any device-mode integration is successful. You can use this callback to perform any operation that you wanted to do once a device-integration is successful.

An example of registering a callback for App Center is as shown:

Copy
await rc.registerCallback("App Center", () => {
  console.log("App Center is ready")
})

The registerCallback method has the following signatures:

Enabling / Disabling Events for Specific Destinations

The React Native SDK lets you enable or disable sending events to a specific destination or all the destinations to which the source is connected. You can specify these destinations by creating an object as shown:

Copy
const options = {
  integrations: {
    // default value for `All` is true
    All: false,
    // specifying destination by its display name
    Amplitude: true,
    Mixpanel: false,
  },
}

There are two methods in which you can pass the destinations specified in the above snippet to the SDK:

1. Passing the destinations while initializing the SDK:

This is helpful when you want to enable or disable sending the events across all the event calls made using the SDK to the specified destinations.

Copy
rudderClient.setup(WRITE_KEY, config, options)

2. Passing the destinations while making any event call:

This approach is helpful when you want to enable or disable sending only a particular event to the specified destinations, or if you want to override the specified destinations passed with the SDK initialization (as described in the method above) for a particular event.

Copy
rudderClient.track(
  "test_track_event",
  {
    test_key_1: "test_value_1",
  },
  options
)

External ID

You can pass your custom userId along with standard userId in your identify calls. We add those values under context.externalId. The following code snippet shows a way to add externalId to your identify request.

Copy
const options = {
  externalIds: [
    {
      id: "some_external_id_1",
      type: "brazeExternalId",
    },
  ],
}
rudderClient.identify(
  "test_userId",
  {
    email: "testuser@example.com",
    location: "UK",
  },
  options
)

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.

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:

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

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

Copy
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:

Copy
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:

Copy
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.

How do I get the user traits after making an identify call?

You can get the user traits after making an identify call as shown:

Copy
const rudderContext = await rc.getRudderContext()
console.log("Traits are : " + JSON.stringify(rudderContext.traits))

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!