Quickstart

Search…
Quickstart
The Roam Android SDK makes it quick and easy to build a location tracker for your Android app. We provide powerful and customizable tracking modes and other features.
Requirements
To use the Roam SDK,
Get yourself a free Roam Account. No credit card is required.
Create a project and add an Android app to the project.
You need the PUBLISHABLE_KEY (available in your project settings) to initialize the SDK.
Now, you’re ready to integrate the SDK into your Android application. 
Roam Android SDK requires Android Studio 2.0 or later and is compatible with apps targeting Android SDK Version 16 or above.
Run the example application
The Roam Example repository on GitHub includes sample applications that demonstrate the use of the v3 Roam SDK for Android.
To run an example app, clone this repository, navigate to the example app in paths Example/ , add your publishable YOUR-PUBLISHABLE-KEY key in MainApplication.java, and run the app.
Make sure the package name is the same as the one registered on our Roam dashboard.
GitHub - roam-ai/roam-android: Android Location SDK. High accuracy and battery efficient location SDK for Android by Roam.ai
GitHub
Android Studio Setup
To use the Android SDK in a project, add the SDK as a build dependency and sync the project.
1.Go to Android Studio > New Project > Minimum SDK
2.Select API 16: Android 4.1.0 (Jelly Bean) or higher and create a project
3.After you create a new project, open Gradle Scripts > build.gradle (Project: <your_project>) and do the following:
1.Add the following to the build script {repositories {}} section of the build.gradle (Project)file:
1
mavenCentral()
Copied!
Sync and close build.gradle (Project: <your_project>)
SDK Installation
Gradle Installation
To install the SDK for your project via Gradle in Android Studio, add the maven below to your project build.gradle file.
1
repositories {
2
    maven {
3
        url 'https://com-roam-android.s3.amazonaws.com/'
4
    }
5
}
Copied!
add the dependencies below to your app build.gradle file.
1
dependencies {
2
 implementation 'com.roam.sdk:roam-android:0.0.23'
3
}
Copied!
Then sync Gradle.
Manual Installation
​Download and unzip the Roam SDK.
1.Open Android Studio and add the SDK Roam.aar as a module using File > New > New Module > Import .JAR/.AAR Package.
2.Once Gradle is finished, click File > Project Structure again.
3.Click on the Dependencies tab > click App > click the “+” icon in the top left of the Declared Dependencies section > select Module Dependency > click on Roam-release > press Ok and wait for Gradle to sync again. 
4.Make sure to include the dependencies separately and sync your project.
1
dependencies {
2
    implementation 'com.google.android.gms:play-services-location:17.0.0'
3
    implementation 'com.squareup.retrofit2:retrofit:2.6.2'
4
    implementation 'com.squareup.retrofit2:converter-gson:2.1.0'
5
    implementation 'org.eclipse.paho:org.eclipse.paho.client.mqttv3:1.2.4'
6
    implementation 'org.eclipse.paho:org.eclipse.paho.android.service:1.1.1'
7
}
Copied!
Initialize the SDK
Before initializing the SDK, the below must be imported.
1
import com.roam.sdk.Roam;
Copied!
After importing, add the code below under the Application class onCreate() method. The SDK must be initialized before calling any of the other SDK methods.
Kotlin
Java
1
Roam.initialize(this, "YOUR-SDK-KEY-GOES-HERE")
Copied!
1
Roam.initialize(this, "YOUR-SDK-KEY-GOES-HERE");
Copied!
Request Permission
To request the location for devices running both below/above Android 10, refer to the following piece of code. 
Kotlin
Java
1
if (!Roam.checkLocationServices()) {
2
	Roam.requestLocationServices(this)
3
} else if (!Roam.checkLocationPermission()) {
4
	Roam.requestLocationPermission(this)
5
} else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q && !Roam.checkBackgroundLocationPermission()) {
6
	Roam.requestBackgroundLocationPermission(this)
7
}
Copied!
1
if (!Roam.checkLocationServices()) {
2
       Roam.requestLocationServices(this);
3
} else if (!Roam.checkLocationPermission()) {
4
       Roam.requestLocationPermission(this);
5
} else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q && !Roam.checkBackgroundLocationPermission()) {
6
       Roam.requestBackgroundLocationPermission(this);
7
}
Copied!
Location Tracking
Start Tracking
Kotlin
Java
1
Roam.startTracking(TrackingMode)
Copied!
1
Roam.sTracking(TrackingMode);
Copied!
Specify the tracking modes while you use the Roam.startTrackingmethod.
Tracking Modes
Adaptive Tracking
Roam has three default tracking modes along with a custom version. They differ based on the frequency of location updates and battery consumption. The higher the frequency, the higher the battery consumption. You must use the foreground service for continuous tracking.
Mode
Battery usage
Updates every 
Optimized for/advised for 
Active 
6% - 12% 
25 ~ 250 meters 
Ride Hailing / Sharing
Balanced
3% - 6% 
50 ~ 500 meters 
On Demand Services
Passive
0% - 1%
100 ~ 1000 meters 
Social Apps
Kotlin
Java
1
// active tracking
2
Roam.startTracking(RoamTrackingMode.ACTIVE)
3
// balanced tracking
4
Roam.startTracking(RoamTrackingMode.BALANCED)
5
// passive tracking
6
Roam.startTracking(RoamTrackingMode.PASSIVE)
Copied!
1
// active tracking
2
Roam.startTracking(RoamTrackingMode.ACTIVE);
3
// balanced tracking
4
Roam.startTracking(RoamTrackingMode.BALANCED);
5
// passive tracking
6
Roam.startTracking(RoamTrackingMode.PASSIVE);
Copied!
Distance Interval Tracking
The SDK also provides a custom tracking mode that allows you to customize and build your own tracking modes.
With distance interval tracking you create a tracking mode with a distance interval in meters of your choice. 
Type
Unit
Unit Range
Distance Interval
Meters
1m ~ 2500m
Distance between location updates example code:
Kotlin
Java
1
// Define a custom tracking method with desired distance interval, stop duration and accuracy
2
RoamTrackingMode trackingMode = new RoamTrackingMode.Builder(<DISTANCE-FILTER-IN-METERS>, <STOP-INTERVAL-IN-SECONDS>)
3
                .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
4
                .build()
5
// Start the tracking with the above created custom tracking method
6
Roam.startTracking(trackingMode)
Copied!
1
// Define a custom tracking method with desired distance interval, stop duration and accuracy
2
RoamTrackingMode trackingMode = new RoamTrackingMode.Builder(<DISTANCE-FILTER-IN-METERS>, <STOP-INTERVAL-IN-SECONDS>)
3
                .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
4
                .build();
5
// Start the tracking with the above created custom tracking method
6
Roam.startTracking(trackingMode);
Copied!
Time Interval Tracking
With Time Interval Tracking you can create a tracking mode with the time interval (in seconds) of your choice. 
Type
Unit
Unit Range
Time Interval
Seconds
10s ~ 10800s
Time between location updates example code:
Kotlin
Java
1
// Define a custom tracking method with desired time interval and accuracy
2
RoamTrackingMode trackingMode = new RoamTrackingMode.Builder(<TIME-INTERVAL-IN-SECONDS>)
3
                .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
4
                .build()
5
// Start the tracking with the above created custom tracking method
6
Roam.startTracking(trackingMode)
Copied!
1
// Define a custom tracking method with desired time interval and accuracy
2
RoamTrackingMode trackingMode = new RoamTrackingMode.Builder(<TIME-INTERVAL-IN-SECONDS>)
3
                .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
4
                .build();
5
// Start the tracking with the above created custom tracking method
6
Roam.startTracking(trackingMode);
Copied!
You may see a delay if the user's device is in low power mode or has connectivity issues.
Stop Tracking
To stop tracking, use the method below.
Kotlin
Java
1
Roam.stopTracking()
Copied!
1
Roam.stopTracking();
Copied!
Location Listeners
Listeners are needed to consume the location or event data from the SDK. To enable listeners, ensure the following:
To listen to location updates, create a class that extends RoamReceiver. 
Register the receiver by adding a receiver element to the application element in your manifest.
Note: For self-tracking, you can only listen to location, error, and offline trip status data since the locations are not being sent to our servers for processing events.
1
<application>
2
        ...
3
     <receiver android:name=".LocationReceiver"
4
                    android:enabled="true"
5
                    android:exported="false">
6
         <intent-filter>
7
         <action android:name="com.roam.android.RECEIVED"/>
8
         </intent-filter>
9
     </receiver>
10
         ...
11
</application>
Copied!
Add the code to the receiver.
Kotlin
Java
1
public class LocationReceiver extends RoamReceiver {
2
​
3
    @Override
4
    public void onLocationUpdated(Context context, RoamLocation roamLocation) {
5
        super.onLocationUpdated(context, roamLocation);
6
        // receive own location updates here
7
	// do something with location data using location
8
	// roamLocation.getActivity();
9
	// roamLocation.getRecordedAt();
10
	// roamLocation.getTimezoneOffset();
11
	// roamLocation.getMetadata();
12
	// roamLocation.getBatteryStatus();
13
	// roamLocation.getNetworkStatus();
14
	// roamLocation.getLocation().getLatitude();
15
	// roamLocation.getLocation().getLongitude();
16
	// roamLocation.getLocation().getBearing();
17
	// roamLocation.getLocation().getAltitude();
18
	// roamLocation.getLocation().getAccuracy();
19
	// roamLocation.getLocation().getSpeed();
20
	// roamLocation.getLocation().getProvider();
21
	// roamLocation.getLocation().getTime();
22
	// roamLocation.getLocation().getVerticalAccuracyMeters();
23
    }
24
​
25
    @Override
26
    public void onError(Context context, RoamError roamError) {
27
    	// receive error message here
28
        // roamError.getCode());	
29
        // roamError.getMessage());
30
    }
31
​
32
}
Copied!
1
public class LocationReceiver extends RoamReceiver {
2
​
3
    @Override
4
    public void onLocationUpdated(Context context, RoamLocation roamLocation) {
5
        super.onLocationUpdated(context, roamLocation);
6
	// receive own location updates here
7
	// do something with location data using location
8
	// roamLocation.getActivity();
9
	// roamLocation.getRecordedAt();
10
	// roamLocation.getTimezoneOffset();
11
	// roamLocation.getMetadata();
12
	// roamLocation.getBatteryStatus();
13
	// roamLocation.getNetworkStatus();
14
	// roamLocation.getLocation().getLatitude();
15
	// roamLocation.getLocation().getLongitude();
16
	// roamLocation.getLocation().getBearing();
17
	// roamLocation.getLocation().getAltitude();
18
	// roamLocation.getLocation().getAccuracy();
19
	// roamLocation.getLocation().getSpeed();
20
	// roamLocation.getLocation().getProvider();
21
	// roamLocation.getLocation().getTime();
22
	// roamLocation.getLocation().getVerticalAccuracyMeters();
23
    }
24
​
25
    @Override
26
    public void onError(Context context, RoamError roamError) {
27
    	// receive error message here
28
        // roamError.getCode());	
29
        // roamError.getMessage());
30
    }
31
​
32
}
Copied!