Skip to main content
Userpilot React Native Module enables you to capture user insights and deliver personalized in-app experiences in real time. With just a one-time setup, you can immediately begin leveraging Userpilot’s analytics and engagement features to understand user behaviors and guide their journeys in-app. This document provides a step-by-step walkthrough of the installation and initialization process, as well as instructions on using the SDK’s public APIs.

​
Prerequisites

​
React Native

Your application should use React Native version 0.73 or above. Applications using Expo should use version 50 or above. The New Architecture is fully supported.

​
Android

React Native - your application should use React Native version 0.73 or above. Applications using Expo should use version 50 or above. The New Architecture is fully supported starting with version 4.4.0. Android - your application’s build.gradle must have a compileSdk of 35+ and minSdk of 21+, and use Android Gradle Plugin (AGP) 8.6+ (8.8.2+ recommended). 
android {
    compileSdk 35
    defaultConfig {
        minSdk 21
    }
}
For AGP versions < 8.8.2 (React Native versions < 0.79), you may need to add the following line to your gradle.properties: android.experimental.lint.version = 8.8.2

​
iOS

Your application must target iOS 13+ to install and render Userpilot content. Update the iOS project xcodeproj to set the deployment target, if needed. In the application’s Podfile , include at least this minimum version. 
# Podfile
platform :ios, '13.0'

​
Installation

Add the Userpilot React Native Module dependency to your application.
  1. In your app’s root directory, install the Userpilot React Native Module. You can fetch the latest version from here.
npm install @userpilot/react-native
  1. Under your application’s ios folder, run
pod install
Note: You do not need to manually update your Podfile to add Userpilot.

​
Initialization

To use Userpilot, initialize it once in your Application class. This ensures the SDK is ready as soon as your app starts. Update your Application class. Replace <APP_TOKEN> with your Application Token, which can be fetched from your Environments Page. 
import * as Userpilot from '@userpilot/react-native'

await Userpilot.setup('<APP_TOKEN>', { logging: true })

​
Using the SDK

Once initialized, the SDK provides straightforward APIs for identifying users, tracking events, and screen views.

​
Identifying Users

This API is used to identify unique users and companies (groups of users) and set their properties. Once identified, all subsequent tracked events and screens will be attributed to that user.
ImportantIt’s crucial to call the Userpilot identify function; without it, Userpilot won’t be able to recognize your users, and mobile content won’t be displayed to them.
Recommended Usage:
  • On user authentication (login): Immediately call identify when a user signs in to establish their identity for all future events.
  • On app launch for authenticated users: If the user has a valid authenticated session, call identify at app launch.
  • Upon property updates: Whenever user or company properties change.
// API
identify(userID: string, properties?: Object, company?: Object): void;

// Example
userpilot.identify(
  '<USER_ID>',
  {
      'name' : "John Doe",
      "email" : 'user@example.com',
      'created_at' : '2019-10-17',
      'role' : 'Admin'
  },
  {
      'id' : '<COMPANY_ID>',
      'name': 'Acme Labs',
      'created_at': '2019-10-17',
      'plan' : 'Free'
  }
)
Properties Guidelines
  • Key id is required in company properties, to identify a unique company.
  • Userpilot supports String, Numeric, and Date types.
  • Make sure you’re sending date values in ISO8601 format.
  • If you are planning to use Userpilot’s localization features, make sure you are passing user property locale_code with a value that adheres to ISO 639-1 format.
  • Userpilot’s reserved properties’ have pre-determined types and improve profiles interface in the dashboard:
    • Use key email to pass the user’s email.
    • Use key name to pass the user’s or company’s name.
    • Use key created_at to pass the user’s or company’s signed up date.
Notes
  • Ensure the User ID source is consistent across Web, Android, and iOS.
  • While properties are optional, setting them enhances Userpilot’s segmentation capabilities.

​
Tracking Screens (Required)

Calling screen is crucial for unlocking Userpilot’s core engagement and analytics capabilities. When a user navigates to a particular screen, invoking screen records that view and triggers any eligible in-app experiences. Subsequent events are also attributed to the most recently tracked screen, providing context for richer analytical insights. For these reasons, we strongly recommend tracking all of your app’s screen views. 
// API
screen(title: string): void;

// Example
userpilot.screen('Profile');

​
Tracking Events

Log any meaningful action the user performs. Events can be button clicks, form submissions, or any custom activity you want to analyze. Optionally, you can pass metadata with the event to provide specific context. 
// API
track(name: string, properties?: Object): void;

// Example
userpilot.track('Added to Cart', {'itemId' : 'sku_456', 'price' : 29.99})

​
Logging Out

When a user logs out, call logout() to clear the current user context. This ensures subsequent events are no longer associated with the previous user. 
userpilot.logout()

​
Anonymous Users

If a user is not authenticated, call anonymous() to track events without a user ID. This is useful for pre-signup flows or guest user sessions. 
userpilot.anonymous()
Anonymous users count towards your Monthly Active Users usage. Consider your MAU limits before using this API.

​
Experience

Triggers a specific experience programmatically using it’s ID. This API allows you to manually initiate an experience within your application. 
// API
triggerExperience(experienceID: string): void;

// Example
userpilot.triggerExperience('<EXPERIENCE_ID>')
To end current active experience 
userpilot.endExperience()

​
Configurations (Optional)

ParameterTypeDescription
loggingBooleanEnable or Disable logs for SDK

Default: false
disableRequestPushNotificationsPermissionBooleanDisable request push notifications permission by SDK.

Default: false
useInAppBrowserBooleanconfiguration to indicate when to open the URL inside CustomTabsIntent or not.

Default: false