HomeContactDashboard

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:

  1. Locate these files at: node_modules/roam-reactnative/ios/

  2. Open your Xcode workspace: ios/<project_name>.xcworkspace

  3. Drag RNRoam.h and RNRoam.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 Android

  • Native 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.

PreviousiOSNextAWS S3

Last updated

Was this helpful?