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 features.

Requirements

To use the Roam SDK, the following things are required:

  • Get yourself a free Roam Account. No credit card required.

  • Create a project and add an Android app to the project.

  • You need the PUBLISHABLE_KEY in your project settings which you’ll need to initialize the SDK.

  • Now, you’re ready to integrate the SDK into your Android application.

The 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 apps that demonstrate the use of the v3 Roam SDK for Android.

To run the example app, clone this repository, navigate to the example app in paths Example/ and 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 in our Roam dashboard.

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:

      mavenCentral()

Sync and close build.gradle (Project: <your_project>)

SDK Installation

Gradle Installation

Install the SDK to your project via Gradle in Android Studio, add the maven below in your project build.gradle file.

repositories {
maven {
url 'https://com-roam-android.s3.amazonaws.com/'
}
}

add the dependencies below in your app build.gradle file.

dependencies {
implementation 'com.roam.sdk:roam-android:0.0.3'
}

Then sync Gradle.

Manual Installation

Download and unzip 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 in Declared Dependencies section > select Module Dependency > click on Roam-release > press Ok and wait for Gradle to sync again and include the dependencies separately and sync your project.

  4. Wait for Gradle to sync again and include the dependencies separately and sync your project.

dependencies {
implementation 'com.google.android.gms:play-services-location:17.0.0'
implementation 'com.squareup.retrofit2:retrofit:2.6.2'
implementation 'com.squareup.retrofit2:converter-gson:2.1.0'
implementation 'org.eclipse.paho:org.eclipse.paho.client.mqttv3:1.2.4'
implementation 'org.eclipse.paho:org.eclipse.paho.android.service:1.1.1'
}

Initialize SDK

Before initializing the SDK, the below must be imported.

import com.roam.sdk.Roam;

After import, add the below code under the Application class onCreate() method. The SDK must be initialised before calling any of the other SDK methods.

Kotlin
Java
Kotlin
Roam.initialize(this, "YOUR-SDK-KEY-GOES-HERE")
Java
Roam.initialize(this, "YOUR-SDK-KEY-GOES-HERE");

Request Permission

To request the location for devices running both below/above Android 10.

Kotlin
Java
Kotlin
if (!Roam.checkLocationServices()) {
Roam.requestLocationServices(this)
} else if (!Roam.checkLocationPermission()) {
Roam.requestLocationPermission(this)
} else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q && !Roam.checkBackgroundLocationPermission()) {
Roam.requestBackgroundLocationPermission(this)
}
Java
if (!Roam.checkLocationServices()) {
Roam.requestLocationServices(this);
} else if (!Roam.checkLocationPermission()) {
Roam.requestLocationPermission(this);
} else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q && !Roam.checkBackgroundLocationPermission()) {
Roam.requestBackgroundLocationPermission(this);
}

Location Tracking

Start Tracking

Kotlin
Java
Kotlin
Roam.startSelfTracking(TrackingMode)
Java
Roam.startSelfTracking(TrackingMode);

Use the tracking modes while you use the Roam.startSelfTracking method.

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 is the battery consumption. You must use foreground service for continuous tracking.

Mode

Battery usage

Updates every

Optimised 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
Kotlin
// active tracking
Roam.startSelfTracking(RoamTrackingMode.ACTIVE)
// balanced tracking
Roam.startSelfTracking(RoamTrackingMode.BALANCED)
// passive tracking
Roam.startSelfTracking(RoamTrackingMode.PASSIVE)
Java
// active tracking
Roam.startTracking(RoamTrackingMode.ACTIVE);
// balanced tracking
Roam.startTracking(RoamTrackingMode.BALANCED);
// passive tracking
Roam.startTracking(RoamTrackingMode.PASSIVE);

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
Kotlin
// Define a custom tracking method with desired distance interval, stop duration and accuracy
RoamTrackingMode trackingMode = new RoamTrackingMode.Builder(<DISTANCE-FILTER-IN-METERS>, <STOP-INTERVAL-IN-SECONDS>)
.setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
.build()
// Start the tracking with the above created custom tracking method
Roam.startSelfTracking(trackingMode)
Java
// Define a custom tracking method with desired distance interval, stop duration and accuracy
RoamTrackingMode trackingMode = new RoamTrackingMode.Builder(<DISTANCE-FILTER-IN-METERS>, <STOP-INTERVAL-IN-SECONDS>)
.setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
.build();
// Start the tracking with the above created custom tracking method
Roam.startTracking(trackingMode);

Time Interval Tracking

With time interval tracking you create a tracking mode with a time interval in seconds of your choice.

Type

Unit

Unit Range

Time Interval

Seconds

10s ~ 10800s

Time between location updates example code:

Kotlin
Java
Kotlin
// Define a custom tracking method with desired time interval and accuracy
RoamTrackingMode trackingMode = new RoamTrackingMode.Builder(<TIME-INTERVAL-IN-SECONDS>)
.setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
.build()
// Start the tracking with the above created custom tracking method
Roam.startSelfTracking(trackingMode)
Java
// Define a custom tracking method with desired time interval and accuracy
RoamTrackingMode trackingMode = new RoamTrackingMode.Builder(<TIME-INTERVAL-IN-SECONDS>)
.setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
.build();
// Start the tracking with the above created custom tracking method
Roam.startTracking(trackingMode);

You may see a delay if the user's device is in low power mode or has connectivity issues.

Stop Tracking

To stop the tracking use the below method.

Kotlin
Java
Kotlin
Roam.stopSelfTracking()
Java
Roam.stopSelfTracking();

Location Listeners

Listeners are needed to consume the location or event data from the SDK iteself. In order to enable listerners, the below setps are needed.

To listen to location updates create a class that extends RoamReceiver. Then register the receiver by adding a receiver element to the application element in your manifest.

Note: In self tracking, you can listen to only location, error and offline trips status data since the locations are not being sent to our servers for processing events.

<application>
...
<receiver android:name=".LocationReceiver"
android:enabled="true"
android:exported="false">
<intent-filter>
<action android:name="com.roam.android.RECEIVED"/>
</intent-filter>
</receiver>
...
</application>

Then add the code to the receiver.

Kotlin
Java
Kotlin
public class LocationReceiver extends RoamReceiver {
@Override
public void onLocationUpdated(Context context, RoamLocation roamLocation) {
super.onLocationUpdated(context, roamLocation);
// receive own location updates here
// do something with location data using location
// roamLocation.getLocation().getLatitude()
// roamLocation.getLocation().getLongitude());
}
@Override
public void onError(Context context, RoamError roamError) {
// receive error message here
// roamError.getMessage());
}
}
Java
public class LocationReceiver extends RoamReceiver {
@Override
public void onLocationUpdated(Context context, RoamLocation roamLocation) {
super.onLocationUpdated(context, roamLocation);
// receive own location updates here
// do something with location data using location
// roamLocation.getLocation().getLatitude()
// roamLocation.getLocation().getLongitude());
}
@Override
public void onError(Context context, RoamError roamError) {
// receive error message here
// roamError.getMessage());
}
}