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’sbuild.gradle
must have a compileSdk
of 35+ and minSdk
of 21+, and use Android Gradle Plugin (AGP) 8.6+ (8.8.2+ recommended).
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’sPodfile
, include at least this minimum version.
Installation
Add the Userpilot React Native Module dependency to your application.- In your app’s root directory, install the Userpilot React Native Module. You can fetch the latest version from here.
- Under your application’s
ios
folder, run
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.
Configurations (Optional)
Parameter | Type | Description |
---|---|---|
logging | Boolean | Enable or Disable logs for SDK Default: false |
disableRequestPushNotificationsPermission | Boolean | Disable request push notifications permission by SDK. Default: false |
useInAppBrowser | Boolean | configuration to indicate when to open the URL inside CustomTabsIntent or not. Default: false |
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.
- 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.
- 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.
- Use key
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.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.Logging Out
When a user logs out, calllogout()
to clear the current user context. This ensures subsequent events are no longer associated with the previous user.
Anonymous Users
If a user is not authenticated, callanonymous()
to track events without a user ID. This is useful for pre-signup flows or guest user sessions.
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.SDK callbacks
Userpilot SDK provides three types of callbacks:- Navigation Listener
- Analytics Listener
- Experience Listener
Navigation Listener
Triggered when a deep link is invoked from an experience or push notification.Parameters
url: string
– The custom deep link URL that should be handled by the host (client) app.
Analytics Listener
Triggered when the client app reports an analytics event to the SDK.Parameters
analytic: string
– The name or type of the analytic event ("Identify"
,"Screen"
,"Event"
).value: string
– The value associated with the event.properties: Map<string, any>
– Additional key-value pairs providing context for the event.
Experience Listener
Provides callbacks related to the lifecycle of experiences and their steps within the SDK.Callbacks
-
onExperienceStateChanged(id: int, state: string)
Called when the overall state of an experience changes.id
: Experience ID (optional)state
: New state —"Started"
,"Completed"
,"Dismissed"
,"Skipped"
, or"Submitted"
experienceType
:"Flow"
,"Survey"
, or"NPS"
-
onExperienceStepStateChanged(id: int, state: string, experienceId: int, step: int, totalSteps: int)
Called when the state of a specific step in an experience changes.id
: Step IDstate
: New step state —"Started"
,"Completed"
,"Dismissed"
,"Skipped"
, or"Submitted"
experienceId
: Associated experience IDexperienceType
:"Flow"
,"Survey"
, or"NPS"
step
: Current step index (optional)totalSteps
: Total number of steps in the experience (optional)
UserpilotExperienceEvent
.
Push Notifications
Userpilot SDK supports handling push notifications to help you deliver targeted messages and enhance user engagement. For Expo apps, setting up Userpilot Push Notifications requires configuration through the Expo Config Plugin. Refer to the official documentation for detailed setup instructions.AndroidSetup:
Prerequisites It is recommended to configure your Android push settings in the Userpilot Settings Studio before setting up push notifications in your app. To obtain the required keys and configuration details, please refer to the Android Push Notification Guide. Setting up This guide assumes this is the first time code is being added to your project related to setting up push notifications using Google services (Firebase Cloud Messaging). In the case your project is already configured for push, proceed to Step 2. Step 1. Add Firebase Follow the steps in the official Google documentation on How to add Firebase to your project. Step 2. Request Notifications Permission Starting from Android 13 (API level 33), apps **must explicitly request the **POST_NOTIFICATIONS
permission in order to display push notifications.
The Userpilot ReactNative module automatically requests push notifications permission on its own.
Step 3. Add the Userpilot Firebase Messaging Service
Firebase connects to your app through a <service>
. Go to your Manifest file under example -> android -> app -> manifest
and add:
UserpilotFirebaseMessagingService
to your service class.
intent-filter
in your app’s **entry **Activity
under example -> android -> app -> manifest
.
This configuration enables deep linking based on a custom scheme defined in your app.
Define the Deep Link Scheme In your userpilot.xml
configuration file, you should have defined a value for userpilot_push_notification
, check Step 5.
Update Manifest file to include the intent-filter as below. Make sure to set host="sdk"
.
MainActivity
under example -> android -> app
, pass intent to Userpilot SDK to handle it.
<resources>
properties. In order change those properties create a file under res/values
under example -> android -> app
and set it to desired values.
iOS Setup
Prerequisites It is recommended to configure your iOS push settings in the Userpilot Settings Studio before setting up push notifications in your app. To obtain the required keys and configuration details, please refer to the iOS Push Notification Guide. Enabling Push Notification Capabilities In Xcode, navigate to the Signing & Capabilities section of your main app target and add the Push Notifications capability. Configuring Push Notifications The Userpilot iOS SDK supports receiving push notification so you can reach your users whenever the moment is right. There are two options for configuring push notification: automatic or manual. Automatic configuration is the quickest and simplest way to configure push notifications and is recommended for most customers. Automatic App Configuration Automatic configuration takes advantage of swizzling to automatically provide the necessary implementations of the requiredUIApplicationDelegate
and UNUserNotificationCenterDelegate
methods.
To enable automatic configuration, call Userpilot.enableAutomaticPushConfig()
from UIApplicationDelegate.application(_:didFinishLaunchingWithOptions:)
inside example -> ios -> AppDelegate.swift
.
Step 2. Register for push notifications
Step 3. Set push token for Userpilot
Step 4. Enable push response handling
Step 5. Configure foreground handling Full source code: