How to set up the Roam SDK on Android

Chinmayee Deshpande

Technical Documentation Writer

•

November 1, 2022

t Tweet

f Share

in Share

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.

What is Roam's SDK?

Roam SDK is a convenient Software Development Kit that helps you easily add location tracking to your app without the complexity of REST API calls. Our main product offers accuracy, battery efficiency, and customizable location tracking with the following additional features:

Always-on location tracking to track users’ location at all times regardless of the application state (foreground, background, terminated)
Offline location tracking to track users’ location when they are not connected to the internet.
Location spoofing prevention prevents your users from faking their location.
Location tracking modes to customize the setup and optimize battery usage and data collection frequency.

Prerequisites

The following are the prerequisites for the Roam SDK installation.

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.

Note: Roam Android SDK requires Android Studio 2.0 or later and is compatible with apps targeting Android SDK Version 16 or above.

Android Studio Setup

To use the Android SDK in a project, add the SDK as a build dependency and sync the project.

Go to Android Studio > New Project > Minimum SDK
Select API 16: Android 4.1.0 (Jelly Bean) or higher and create a project.

Now that Android Studio is set up, the following sections cover SDK installation and initialization.

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.

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

Add the dependencies below to your app build.gradle file.

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

Then sync Gradle.

Manual Installation

Download and unzip the Roam SDK.

Open Android Studio and add the SDK Roam.aar as a module using File > New > New Module > Import .JAR/.AAR Package.
Once Gradle is finished, click File > Project Structure again.
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.
Make sure to 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 the SDK

Before initializing the SDK, the below must be imported.

import com.roam.sdk.Roam;

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.

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

Creating Users

Once the SDK is initialized, we need to create or get a user to start tracking and use other methods. Every user created will have a unique Roam identifier which will be used later to login and access developer APIs. We call it the Roam userID.

Roam.createUser("YOUR-USER-DESCRIPTION-GOES-HERE", new RoamCallback() { @Override public void onSuccess(RoamUser roamUser) { // Access Roam user data below // roamUser.getUserId(); // roamUser.getDescription(); // roamUser.getEventListenerStatus(); // roamUser.getLocationListenerStatus(); // roamUser.getLocationEvents(); // roamUser.getGeofenceEvents(); // roamUser.getMovingGeofenceEvents(); // roamUser.getTripsEvents(); } @Override public void onFailure(RoamError roamError) { // Access error code & message below // roamError.getCode(); // roamError.getMessage(); } });

Getting Users

If you already have a Roam userID which you would like to reuse instead of creating a new user, use the below to get the user session.

Roam.getUser("YOUR-ROAM-USER-ID", new RoamCallback() { @Override public void onSuccess(RoamUser roamUser) { // Access Roam user data below // roamUser.getUserId(); // roamUser.getDescription(); // roamUser.getEventListenerStatus(); // roamUser.getLocationListenerStatus(); // roamUser.getLocationEvents(); // roamUser.getGeofenceEvents(); // roamUser.getMovingGeofenceEvents(); // roamUser.getTripsEvents(); } @Override public void onFailure(RoamError roamError) { // Access error code & message below // roamError.getCode(); // roamError.getMessage(); } });

Request Permissions

To request the location for devices running both below/above Android 10, refer to the following piece of code.

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

You may start tracking the user location using the below method.

Start Tracking

To start tracking the user location, use the following SDK method.

// active tracking Roam.startTracking(RoamTrackingMode.ACTIVE); // balanced tracking Roam.startTracking(RoamTrackingMode.BALANCED); // passive tracking Roam.startTracking(RoamTrackingMode.PASSIVE);

To know more about the different tracking modes, refer the official documentation.

Stop Tracking

To stop tracking, use the below method.

Roam.stopTracking()

Try an example App

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.

Want to know how Roam provides location solutions?

Thank you for reading! If you want to learn more about our Location SDK for Android then check out our docs page's here.

‍

Unlock Location Technology

Get started Contact us

Chinmayee Deshpande

Technical Documentation Writer

•

November 1, 2022