React Native
The Roam React Native SDK brings continuous, battery-optimized location tracking to cross-platform apps built with React Native. This guide walks you through integrating the SDK — from installation and user setup to real-time tracking and optional batch sync.
Prerequisites
Before you begin, make sure you have:
Access to the Roam Dashboard
A project created with your app’s Bundle ID
Your PUBLISHABLE_KEY from the dashboard
A working React Native project
Node.js and either npm or yarn
For iOS: Xcode 14.0+, iOS 12 or later
For Android: Android SDK 21+
Already set up your project on the dashboard? If not, follow the instructions in the Getting Started section.
Important: Make sure your Bundle ID and Android Package Name exactly match the ones configured on the Roam Dashboard.
The SDK will fail to initialize if there's a mismatch.
Step 1: Install the SDK
The first step in integrating the Roam SDK in your React Native project is to install the official Roam package. This wraps our native SDKs for Android and iOS into a single JavaScript interface.
1.1 Add Roam SDK via NPM or Yarn
Use either npm
or yarn
to install the Roam SDK:
npm install roam-reactnative --save
# or
yarn add roam-reactnative
1.2 Install Peer Dependencies
You must install all the required peer dependencies and link native modules:
npx pod-install
If you're using React Native 0.60+, autolinking should take care of native bindings. Just make sure CocoaPods is installed and run npx pod-install
inside the ios/ directory
.
Step 2: Android Setup
To enable Roam’s location tracking capabilities on Android, you need to configure the native Android project inside your React Native app.
2.1 Add Repositories
Add the following repositories inside your android/build.gradle
or app/build.gradle
file:
repositories {
mavenCentral()
maven { url 'https://com-roam-android.s3.amazonaws.com/' }
}

2.2 Add SDK Dependencies
Include the Roam SDK dependency in your app/build.gradle
under dependencies
:
dependencies {
implementation 'com.roam.sdk:roam-android:0.1.41'
implementation "com.roam.sdk:roam-batch-android:0.1.41"
}
2.3 Import & Initialise the SDK
In your android/app/src/main/java/<your_package_name>/MainApplication.java
, import and initialize the SDK in the onCreate()
method:
import com.roam.sdk.Roam;
import com.roam.roam_batch_connector.RoamBatch;
@Override
public void onCreate() {
super.onCreate();
Roam.initialize(this, "YOUR-SDK-KEY");
RoamBatch.initialize(this)
}
2.4 Add LocationService
Download and add the LocationService.java file into your android/app/src/main/java/<your_package_name>/
directory.

2.5 Register LocationService in AndroidManifest
In android/app/src/main/AndroidManifest.xml
, register the service:
<service
android:name=".LocationService"
android:enabled="true"
android:exported="false"
android:foregroundServiceType="location" />
2.6 Set Foreground Notification
Call Roam.setForegroundNotification()
in your tracking function to comply with Android background location policies:
if (Platform.OS === 'android') {
Roam.setForegroundNotification(
true,
"<App Name>",
"Tap to open",
"mipmap/ic_launcher",
"<Package Name>.MainActivity",
"<Package Name>.LocationService"
);
}
2.7 Disable New Architecture
In android/gradle.properties
, make sure to disable the new React Native architecture by adding:
newArchEnabled=false
Step 3: iOS Setup
To enable Roam’s location tracking features on iOS, you’ll need to install dependencies, configure permissions, and manually link native files.
3.1 Install CocoaPods Dependencies
Make sure your iOS project is using Xcode 14+ and supports iOS 12 or later. Open the .xcworkspace
file in Xcode and verify that:
Your Deployment Target is set to at least iOS 12.0
Your Bundle Identifier exactly matches the one used in the Roam Dashboard
Then run:
cd ios && pod install && cd ..
3.2 Add Location Permissions
In your ios/<project_name>/Info.plist
file, add the required keys for location access:
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We use your location for tracking and app features.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>We use your location for tracking and app features.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>We use your location for tracking and app features.</string>
3.3 Link Native iOS Files
Manually add RNRoam.h
and RNRoam.m
to your project:
Locate these files at:
node_modules/roam-reactnative/ios/
Open your Xcode workspace:
ios/<project_name>.xcworkspace
Drag
RNRoam.h
andRNRoam.m
into your project’s root directory in Xcode. Choose "Create groups" when prompted.
3.4 Verify Bridging Header
Ensure the bridging header includes the correct reference for Roam:
#import "RNRoam.h"

3.5 Import & Initialize SDK
Ensure your app calls Roam.initialize()
with the correct SDK key and that your Bundle ID matches what's configured on the Roam dashboard.


Step 4: Request Location Permissions
Before starting location tracking, you must request location permissions from the user on both Android and iOS. The Roam SDK provides a cross-platform method to handle this.
4.1 Request Permission in React Native
Call the following method in your App.js
or appropriate initialization file:
// Requests location access on both iOS and Android
Roam.requestLocationPermission();
This method handles:
ACCESS_FINE_LOCATION
&ACCESS_COARSE_LOCATION
for AndroidNative iOS location dialog with the descriptions defined in
Info.plist
Step 5: Start & Stop Tracking
Once permissions are granted, you can initiate and stop location tracking at any time. Roam SDK supports multiple tracking modes optimized for different use cases.
5.1 Start Tracking
Call the method below to begin location tracking:
Roam.startTracking("BALANCED");
To stop receiving location updates, call:
Roam.stopTracking();
Step 6: Listen to Location Updates
After starting tracking, use the Roam listener to receive real-time location updates. These updates contain detailed contextual information, including coordinates, activity state, and timestamp.
6.1 Enable Listener
Use Roam.startListener()
to begin listening to location updates:
Roam.startListener("location", (location) => {
console.log("Location Update:", location);
});
6.2 Location Data Format
Each update includes a rich payload with user activity, coordinates, speed, and accuracy:
[
{
"activity": "S", // S = Stationary, W = Walking, D = Driving
"location": {
"accuracy": 22.68,
"latitude": 10.35,
"longitude": 78.00,
"speed": 0
},
"recordedAt": "2024-11-19T12:00:00Z",
"userId": "12345abcdef"
}
]
To stop receiving updates:
Roam.stopListener("location");
🎉 You’re All Set!
You’ve successfully completed the full Roam React Native SDK integration — from installing the SDK and configuring platform-specific setup, to requesting permissions, starting location tracking, and listening to real-time updates.
Your app is now ready to:
Continuously track user location with battery-efficient background support
Receive real-time updates through the
startListener
method
If you’ve followed each step and are seeing location updates in your terminal or device logs, your integration is working correctly.
Need help? Explore our FAQs, try the React Native sample project on GitHub, or contact our support team for assistance.
Last updated
Was this helpful?