1 of 100

Roam v1

Introduction

Our Roam Docs contain instructions on how to integrate and use our location SDKs and APIs. Each section walks you through the step-by-step process with source code, examples, and references.

SDKs

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.

APIs

Our REST APIs allow you to go beyond simple location tracking:

Geofencing - static and moving geofences with events.
Insights - detailed location information about your users' patterns.
Trips - full trip management for mobility and on-demand services.
Nearby - find nearby users and geofences.

Getting Started

Learn how to easily implement Roam location technology.

1. Create a Roam Account

Get started with Roam by creating a free account. The account gives you access to all our location products, project creation and dashboard with a full overview of your usage and spending.

2. Try our example app

During the signup process, download the Roam Test App. It’s our demo application for Android and iOS that showcases the basic functionality of Roam location technology.

3. Start integrating

Read our Roam Docs for Android and iOS for instructions about how to effectively integrate and use our location SDKs and APIs.

4. Get support

To get more information about our products read our Knowledge Base or contact our support team.

Key Concepts

Learn more about the key concepts of Roam location technology.

Location update

The fundamental component of Roam location tracking. It is a package of data collected about a users’ location that includes latitude, longitude, altitude, speed, direction, activity, and more.

Location module

The Location module defines the desired data flow of a location update. Depending on what you intend to do with the location update we distinguish four different location modules: Tracker, Publisher, Listener, and Processor.

Location Tracker

The location update is collected by the GPS via Roam SDK and stored locally on the mobile device. You may use it if you want simple location tracking and store the location data yourself.

Location Publisher

The location update is collected by the GPS via Roam SDK, sent from the mobile device to the backend server, and stored in the Roam database. You may use it if you want to store the data on Roam servers and go beyond simple location tracking by accessing other Roam products.

Location Listener

The location listener updates the changes in the location through the server to the mobile device.

Location Processor

The Location Processor processes the location updates stored in the database according to the API calls.

Location tracking mode

Location tracking mode allows you to customize your location tracking with varying frequencies of updates and levels of battery drain insights. We differentiate three default modes: Active, Reactive, Passive, and one fully customizable.

Frameworks

Android

Explore all documentation for Android.

Quickstart (Android)

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,

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.

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

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.1.20'
}

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

Roam SDK offers a flexible method of initialization, allowing developers to seamlessly integrate our services into their applications. With our latest update, we've introduced a new initialization approach using Manifest file. This method provides an effortless way to set up your Roam SDK without the need for additional code.

Using Manifest file Initialization:

Optional Parameter: Publish Key
- The publishKey parameter in the initialization method is now optional.
- If you've added your Roam publish key to your project's Manifest file, there's no need to pass the publishKey parameter during initialization.
Configure Your Manifest File:
- In your Manifest file, declare your Roam publish key as follows:
```
<meta-data
 android:name="com.roam.lib.sdk.PUBLISH_KEY"
 android:value="${ROAM_PUBLISH_KEY}" />
```
- Replace ${ROAM_PUBLISH_KEY} with your actual Roam publish key.
Using local.properties (Optional):
- Alternatively, you can use a local.properties file to feed the Roam publish key to the Manifest file.
- In your local.properties file, add the following line, replacing XXXXXXXXXXXXXX with your Roam publish key:
```
ROAM_PUBLISH_KEY = XXXXXXXXXXXXXX
```
- To get Roam publish key from local.properties to Manifest, user must have to add following code in build.gradle(app)
```
defaultConfig {
        Properties properties = new Properties()
        properties.load(project.rootProject.file('local.properties').newDataInputStream())
        manifestPlaceholders = [ROAM_PUBLISH_KEY: "${properties.getProperty('ROAM_PUBLISH_KEY')}"]

    }
```
Initialization Code:
- Initialize Roam SDK in your application class as follows:
- If the publish key is added to the Manifest file, the initialize method can be called without passing the publishable key.

Roam.initialize(this)

Roam.initialize(this);

By following these steps, you can seamlessly initialize Roam SDK using manifest file, simplifying the integration process and saving valuable development time.

Using Application class Initialization:

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")

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

Request Permission

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)
}

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

Roam.startTracking(TrackingMode, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })

Roam.startTracking(TrackingMode, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

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

// active tracking
Roam.startTracking(RoamTrackingMode.ACTIVE, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })
// balanced tracking
Roam.startTracking(RoamTrackingMode.BALANCED, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })
// passive tracking
Roam.startTracking(RoamTrackingMode.PASSIVE, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })

// active tracking
Roam.startTracking(RoamTrackingMode.ACTIVE, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })
// balanced tracking
Roam.startTracking(RoamTrackingMode.BALANCED, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })
// passive tracking
Roam.startTracking(RoamTrackingMode.PASSIVE, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })

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:

// Define a custom tracking method with desired distance interval, stop duration and accuracy
val trackingMode = 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, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })

// 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, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

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:

// Define a custom tracking method with desired time interval and accuracy
val trackingMode = RoamTrackingMode.Builder(<TIME-INTERVAL-IN-SECONDS>)
            .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
            .build()
// Start the tracking with the above created custom tracking method
Roam.startTracking(trackingMode, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })

// 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, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

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.

Roam.stopTracking(object : TrackingCallback {
            override fun onSuccess(s: String) {
              //do something
            }
            override fun onError(roamError: RoamError) {
              //do something
            }
        })

Roam.stopTracking(new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

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

Add the code to the receiver.

class LocationReceiver: RoamReceiver() {
    override fun onLocationUpdated(context: Context?, roamLocations: MutableList<RoamLocation>?) {
        super.onLocationUpdated(context, roamLocations)
        // receive own location updates here
        // do something with location data using location
            for (roamLocation in roamLocations!!){
                roamLocation.activity
                roamLocation.recordedAt
                roamLocation.timezoneOffset
                roamLocation.metadata
                roamLocation.batteryStatus
                roamLocation.networkStatus
                roamLocation.location.latitude
                roamLocation.location.longitude
                roamLocation.location.bearing
                roamLocation.location.altitude
                roamLocation.location.accuracy
                roamLocation.location.speed
                roamLocation.location.provider
                roamLocation.location.time
                roamLocation.location.verticalAccuracyMeters
            }
    }

    override fun onError(context: Context?, roamError: RoamError?) {
        super.onError(context, roamError)
        // receive error message here
         roamError?.code
         roamError?.message
    }
}

public class LocationReceiver extends RoamReceiver {

    @Override
    public void onLocationUpdated(Context context, List<RoamLocation> roamLocations) {
        super.onLocationUpdated(context, roamLocations);
        // receive own location updates here
        // do something with location data using location
        for(RoamLocation roamLocation: roamLocations){
             roamLocation.getActivity();
             roamLocation.getRecordedAt();
             roamLocation.getTimezoneOffset();
             roamLocation.getMetadata();
             roamLocation.getBatteryStatus();
             roamLocation.getNetworkStatus();
             roamLocation.getLocation().getLatitude();
             roamLocation.getLocation().getLongitude();
             roamLocation.getLocation().getBearing();
             roamLocation.getLocation().getAltitude();
             roamLocation.getLocation().getAccuracy();
             roamLocation.getLocation().getSpeed();
             roamLocation.getLocation().getProvider();
             roamLocation.getLocation().getTime();
             roamLocation.getLocation().getVerticalAccuracyMeters();
        }
    }

    @Override
    public void onError(Context context, RoamError roamError) {
        super.onError(context, roamError);
        // receive error message here
         roamError.getCode();	
         roamError.getMessage();
    }
}

Batch Configuration

Batch configuration lets you control the number of location data updates being received in the location listener with the desired frequency and window.

Set Batch Configuration

As the name suggests, this method sets the configuration parameters.

The NetworkState.BOTH indicates the state in which the updates are to be received. It can either be set to online, offline, or both.
The batchCount indicates the size of the location batch.
The batchWindow indicates the time interval for every consecutive update (frequency of updates).

By default, the batch configuration values for both batch count and window are set to 1 and 0 respectively.

Roam.setBatchReceiverConfig(
    NetworkState.BOTH,
    batchCount,
    batchWindow,
    object : RoamBatchReceiverCallback {
        override fun onSuccess(list: List<BatchReceiverConfig>) {
            list[i].networkState
            list[i].batchCount
            list[i].batchWindow
        }
        override fun onFailure(roamError: RoamError) {
            roamError.code
            roamError.message
        }
    })

Roam.setBatchReceiverConfig(NetworkState.BOTH, batchCount,
batchWindow, new RoamBatchReceiverCallback() {
@Override
           public void onSuccess(List<BatchReceiverConfig> batchReceiverConfig) {
                 batchReceiverConfig.get(i).getNetworkState();
                 batchReceiverConfig.get(i).getBatchCount();
                 batchReceiverConfig.get(i).getBatchWindow();
}
@Override
           public void onFailure(RoamError error) {
              error.getMessage();
              error.getCode();
} });

Consider the following call,

Roam.setBatchConfig("NetworkState.Both", 5 , 60)

The batch count value is the number of location updates sent in a batch. In the above case, the value is set to 5. Ideally, the SDK sends 5 updates per batch and the batch window (in the above case, 60) specifies the number of seconds the SDK waits to receive five location updates.

If the SDK receives 5 location updates in less than 60 seconds, the updates are pushed to the listener. If not, it waits for 60 seconds and pushes the location updates regardless of the batch count value.

Success Callback - We receive a list of BatchReceiveConfig objects.

Example response:

[{"batchCount":5,"batchWindow":10,"networkState":"OFFLINE"}, {"batchCount":5,"batchWindow":10,"networkState":"ONLINE"}]

Error Callback: We receive a RoamError object in the error callback.

The available details to get from the RoamError object are: error.getMessage() and error.getCode()

Get Batch Configuration

The get receiver config method allows the user to get the current batch configuration for the location listener.

Roam.getBatchReceiverConfig(object : RoamBatchReceiverCallback {
    override fun onSuccess(list: List<BatchReceiverConfig>) {
        list[i].networkState
        list[i].batchCount
        list[i].batchWindow
    }
    override fun onFailure(roamError: RoamError) {
        roamError.code
        roamError.message
    }
})

Roam.getBatchReceiverConfig(new RoamBatchReceiverCallback() {

@Override
           public void onSuccess(List<BatchReceiverConfig> batchReceiverConfig) {
                 batchReceiverConfig.get(i).getNetworkState();
                 batchReceiverConfig.get(i).getBatchCount();
                 batchReceiverConfig.get(i).getBatchWindow();
}
@Override
           public void onFailure(RoamError error) {
              error.getMessage();
              error.getCode();
} });

The response for the above code is the same as that of the Set Receiver Config method.

Reset Batch Configuration

The Reset Batch Configuration method allows the user to reset the batch config for the location listener.

Roam.resetBatchReceiverConfig(object : RoamBatchReceiverCallback {
    override fun onSuccess(list: List<BatchReceiverConfig>) {
        list[i].networkState
        list[i].batchCount
        list[i].batchWindow
    }
    override fun onFailure(roamError: RoamError) {
        roamError.code
        roamError.message
    }
})

Roam.resetBatchReceiverConfig(new RoamBatchReceiverCallback() {
@Override
           public void onSuccess(List<BatchReceiverConfig> batchReceiverConfig) {
                 batchReceiverConfig.get(i).getNetworkState();
                 batchReceiverConfig.get(i).getBatchCount();
                 batchReceiverConfig.get(i).getBatchWindow();
}
@Override
           public void onFailure(RoamError error) {
              error.getMessage();
              error.getCode();
} });Roam.resetBatchReceiverConfig(object : RoamBatchReceiverCallback {
    override fun onSuccess(list: List<BatchReceiverConfig>) {
        list[i].networkState
        list[i].batchCount
        list[i].batchWindow
    }
    override fun onFailure(roamError: RoamError) {
        roamError.code
        roamError.message
    }
})

Pub/Sub Locations (Android)

Explore how to publish and subscribe locations for Android.

Creating Users

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

Adding metadata to users is optional and you can pass null while creating users to ignore that field.

The "user description" option can be used to update your user information such as name, address or add an existing user ID. Make sure the information is encrypted if you are planning to save personal user information like email or phone number.

You can always set or update user descriptions and meta-data later using the code below.

Get User

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

Location Tracking

To publish and subscribe to location data, startSelfTracking methods have to be changed to startTracking

Start Tracking

Specify the tracking mode while you use the startTracking method Roam.startTracking

Tracking Modes

Custom Tracking Modes

Our SDK also provides a custom tracking mode that allows you to customize and build your own tracking modes.

Distance between location updates example code:

Time between location updates example code:

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.

Publish Locations

Publishing will help publish location data that will be stored in our database and sent to Roam servers for further processing.

Location data will be published and sent to the Roam servers for further processing. The data will be saved on our database servers.

You can now send custom meta-data json values along with location data in publishAndSavemethod.

To stop publishing locations,

Now that you have enabled the location listener, use the below method to subscribe to your own or other user's location updates and events.

UnSubscribe

You can pass an empty user_id which is an optional field from v0.0.14 to unsubscribe from all the users.

Location Listener

Before adding listeners for locations and other data, we need to toggle the listener flags for the user in order to get the data.

To do that, you need to set the location and event listener to true using the below method. By default, the status will be set to false and needs to be set to true in order to stream the location and event updates to the same device or other devices.

You can also get the current status of listeners with the below method.

Toggle Events

To listen to events on the server-side, you should enable events for the user using the method below.

Location Listener

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

Then add the code to the receiver.

SDK Methods (Android)

Explore all of Roam's Android SDK methods.

SDK Configuration (Android)

The first step is to configure the Android SDK.

Set Tracking in AppState

Offline Location Tracking

Allow Mock Location

Roam SDKs reject Mock Locations on the device by default.

Accuracy Engine

To enable accuracy engine for Passive, Active, and Balanced tracking

For Custom tracking modes, you can pass the desired accuracy values in integers ranging from 1 - 150m.

For disabling accuracy engine

Set Foreground Service Notification

Use setForegroundNotification method to notify the user about location tracking in the notification bar. Set ENABLE as true to enable notification and false to disable the notification.

Get Current Location (Android)

Call this method to get the current location of the user at your desired accuracy level.

Current Location

Get the current location of the user. You can set the accuracy between 5 and 100 meters (default is 10). This method has two outputs.

Callback Method which returns the current location with a faster response time. However, the accuracy depends on the current GPS connectivity.
Location Receiver which returns the next two location updates which will have higher accuracy compared to the callback and takes time from a few hundred milliseconds to a couple of seconds based on the GPS and network connectivity.

Roam.getCurrentLocation(accuracy)

Roam.getCurrentLocation(accuracy);

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.

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

Add the code to the receiver.

class LocationReceiver : RoamReceiver() {
      override fun onLocationUpdated(context: Context?, roamLocation: RoamLocation?) {
            // receive own location updates here
            // do something with location data using location
      }
}

public class LocationReceiver extends RoamReceiver {

    @Override
    public void onLocationUpdated(Context context, RoamLocation roamLocation) {
        // receive own location updates here
		    // do something with location data using location
    }
}

To get the current location of the user in the callback, use the following code:

Roam.getCurrentLocation(DesiredAccuracy, accuracy, object : RoamLocationCallback {
            override fun location(location: Location?) {
                // Access location data here
            }
            override fun onFailure(roamError: RoamError) {
                // Access Error code and message here
                // roamError.code
                // roamError.message
            }
})

Roam.getCurrentLocation(DesiredAccuracy, accuracy, new RoamLocationCallback(){
    @Override
    public void location(Location location) {
            // Access location data here
    }
    @Override
    public void onFailure(RoamError roamError) {
            // Access Error code and message here
            // roamError.getCode();
            // roamError.getMessage(); 
    }
});

Parameter

Description

DesiredAccuracy

RoamTrackingMode.DesiredAccuracy.HIGH RoamTrackingMode.DesiredAccuracy.MEDIUM RoamTrackingMode.DesiredAccuracy.LOW

Update Current Location (Android)

Call this method to update the current location of a user.

Using the updateCurrentLocation method, you can update the users' current location. You can set the accuracy between 5 to 100 meters (default is 10).

You can now send custom meta-data json values along with updateCurrentLocation method.

val data = JSONObject() 
data.put("Key", "Value") 
val roamPublish = RoamPublish.Builder() 
                    .metadata(data) 
                    .build() 
Roam.updateCurrentLocation(DesiredAccuracy, accuracy,roamPublish)

JSONObject data = new JSONObject(); 
data.put("Key", "Value"); 
RoamPublish roamPublish = new RoamPublish.Builder() 
                                .metadata(data) 
                                .build(); 
Roam.updateCurrentLocation(DesiredAccuracy, accuracy,roamPublish);

This method should be used only if you need to update the current location of the device with better accuracy. Using this method consistently will consume more battery. The higher the accuracy, the longer the response time. In some cases, it can take up to 30 seconds depending on the GPS signal strength.

Update Location When Stationary (Android)

Call this method to periodically pick up a user's location when they are stationary. Customize the time interval in seconds.

By using this method updateLocationWhenStationary, location will update every x seconds when the device goes into a stationary state.

Except for time-based custom tracking, this will operate in all tracking modes, including active, passive, balance, and distance based custom tracking.

// Enter update interval in seconds
Roam.updateLocationWhenStationary(int i);

Trip v1 SDK Methods (Android)

Explore the Android SDK Methods for Trip API v1. Check out the latest methods if you are using Trips API v2!

Create Trip

Use the code below to create a trip directly from the SDK. Set Boolean value true to create offline trips and false to create online trips.

Roam.createTrip(null, null, Boolean, object : RoamCreateTripCallback {
      override fun onSuccess(roamTrip: RoamCreateTrip) {
            // do something when create trip success
            // access roam trip created timestamp with roamTrip.getCreatedAt
            // access roam trip user id with roamTrip.getUserId
            // access roam trip id with roamTrip.getTripId
      }
            
      override fun onFailure(roamError: RoamError) {
                // do something when get trip details error
                // access roam error code with roamError.getCode()
                // access roam error message with roamError.getMessage()
        }
})

Roam.createTrip(null, null, Boolean, new RoamCreateTripCallback() {
      @Override
      public void onSuccess(RoamCreateTrip roamTrip) {
              // do something when create trip success
              // access roam trip created timestamp with roamTrip.getCreatedAt
              // access roam trip user id with roamTrip.getUserId
              // access roam trip id with roamTrip.getTripId
     }

      @Override
            public void onFailure(RoamError roamError) {
                // do something when get trip details error
                // access roam error code with roamError.getCode()
                // access roam error message with roamError.getMessage()
            }
});

Get Trip Details

Roam.getTripDetails("ROAM-TRIP-ID", object : RoamTripDetailCallback {
      override fun onSuccess(roamTrip: RoamTripDetail) {
              // do something when get trip details success
              // access roam trip created timestamp with roamTrip.getCreatedAt()
              // access roam trip user id with roamTrip.getUserId()
              // access roam trip id with roamTrip.getTripId()
      }
            
      override fun onFailure(roamError: RoamError) {
                // do something when get trip details error
                // access roam error code with roamError.getCode()
                // access roam error message with roamError.getMessage()
        }
})

Roam.getTripDetails("ROAM-TRIP-ID", new RoamTripDetailCallback() {
            @Override
            public void onSuccess(RoamTripDetail roamTrip) {
                // do something when get trip details success
                // access roam trip created timestamp with roamTrip.getCreatedAt()
                // access roam trip user id with roamTrip.getUserId()
                // access roam trip id with roamTrip.getTripId()
            }

            @Override
            public void onFailure(RoamError roamError) {
                // do something when get trip details error
                // access roam error code with roamError.getCode()
                // access roam error message with roamError.getMessage()
            }
});

Start and Stop Trip

Start Trip

Use the code below to start the trip with the previously created tripID.

 Roam.startTrip("ROAM-TRIP-ID", "ROAM-TRIP-DESCRIPTION", object : RoamTripCallback {
        override fun onSuccess(message: String) {
        }
                
        override fun onFailure(roamError: RoamError) {
                // do something when get trip details error
                // access roam error code with roamError.getCode()
                // access roam error message with roamError.getMessage()
        }
})

Roam.startTrip("ROAM-TRIP-ID", "ROAM-TRIP-DESCRIPTION", new RoamTripCallback() {
            @Override
            public void onSuccess(String message) {
            }

            @Override
            public void onFailure(RoamError roamError) {
                // do something when get trip details error
                // access roam error code with roamError.getCode()
                // access roam error message with roamError.getMessage()
            }
});

Stop Trip

Roam.stopTrip("ROAM-TRIP-ID", object : RoamTripCallback {
      override fun onSuccess(message: String) {

      }
            
      override fun onFailure(roamError: RoamError) {
                // do something when get trip details error
                // access roam error code with roamError.getCode()
                // access roam error message with roamError.getMessage()
        }
})

Roam.stopTrip("ROAM-TRIP-ID", new RoamTripCallback() {
            @Override
            public void onSuccess(String message) {
            }

            @Override
            public void onFailure(RoamError roamError) {
                // do something when get trip details error
                // access roam error code with roamError.getCode()
                // access roam error message with roamError.getMessage()
            }
});

Pause and Resume Trip

Pause Trip

Use the code below to pause the trip with the previously started trip id.

Roam.pauseTrip("ROAM-TRIP-ID", object : RoamTripCallback {
      override fun onSuccess(message: String) {

      }
            
      override fun onFailure(roamError: RoamError) {
                // do something when get trip details error
                // access roam error code with roamError.getCode()
                // access roam error message with roamError.getMessage()
        }
})

Roam.pauseTrip("ROAM-TRIP-ID", new RoamTripCallback() {
            @Override
            public void onSuccess(String message) {
            }

            @Override
            public void onFailure(RoamError roamError) {
                // do something when get trip details error
                // access roam error code with roamError.getCode()
                // access roam error message with roamError.getMessage()
            }
});

Resume Trip

To resume the trip,

Roam.resumeTrip("ROAM-TRIP-ID", object : RoamTripCallback {
      override fun onSuccess(message: String) {

      }
            
      override fun onFailure(roamError: RoamError) {
                // do something when get trip details error
                // access roam error code with roamError.getCode()
                // access roam error message with roamError.getMessage()
        }
})

Roam.resumeTrip("ROAM-TRIP-ID", new RoamTripCallback() {
      @Override
      public void onSuccess(String message) {
      }

      @Override
            public void onFailure(RoamError roamError) {
                // do something when get trip details error
                // access roam error code with roamError.getCode()
                // access roam error message with roamError.getMessage()
            }
});

Subscribe to tripStatus using the tripId to get real-time trip status.

//subscribe to trip status
Roam.subscribeTripStatus("ROAM-TRIP-ID")

//subscribe to trip status
Roam.subscribeTripStatus("ROAM-TRIP-ID");

To stop receiving trip status updates, use the method below.

//unsubscribe to trip status
Roam.unSubscribeTripStatus("ROAM-TRIP-ID")

//unsubscribe to trip status
Roam.unSubscribeTripStatus("ROAM-TRIP-ID");

Get Trip Status

Roam.getTripStatus("ROAM-TRIP-ID", object : RoamTripStatusCallback {
      override fun onSuccess(roamTrip: RoamTripStatus) {
                // do something when get trip details success
                // access roam trip distance with roamTrip.getDistance()
                // access roam trip speed with roamTrip.getSpeed()
      }
            
      override fun onFailure(roamError: RoamError) {
                // do something when get trip details error
                // access roam error code with roamError.getCode()
                // access roam error message with roamError.getMessage()
        }
})

Roam.getTripStatus("ROAM-TRIP-ID", new RoamTripStatusCallback() {
            @Override
            public void onSuccess(RoamTripStatus roamTrip) {
                // do something when get trip details success
                // access roam trip distance with roamTrip.getDistance()
                // access roam trip speed with roamTrip.getSpeed()
            }

            @Override
            public void onFailure(RoamError roamError) {
                // do something when get trip details error
                // access roam error code with roamError.getCode()
                // access roam error message with roamError.getMessage()
            }
});

Get Active Trips

To retrieve the active trips, set the Boolean value to true to get offline trips and to false to get online trips.

Roam.activeTrips(Boolean, object : RoamActiveTripsCallback {
        override fun onSuccess(roamTrip: RoamTrip) {
                roamTrip.activeTrips
        }

        override fun onFailure(roamError: RoamError) {
                // do something when get trip details error
                // access roam error code with roamError.getCode()
                // access roam error message with roamError.getMessage()
        }
})

Get Trip Summary

Roam.getTripSummary("ROAM-TRIP-ID", object : RoamTripSummaryCallback {
        override fun onSuccess(roamTrip: RoamTripSummary) {
                // do something when get trip details success
                // access roam trip distance covered with roamTrip.getDistanceCovered
                // access roam trip route with roamTrip.getRoute
                // access roam trip duration with roamTrip.getDuration
                // access roam trip id with roamTrip.getTripId
        }
            
        override fun onFailure(roamError: RoamError) {
                // do something when get trip details error
                // access roam error code with roamError.getCode()
                // access roam error message with roamError.getMessage()
        }
})

Roam.getTripSummary("ROAM-TRIP-ID", new RoamTripSummaryCallback() {
            @Override
            public void onSuccess(RoamTripSummary roamTrip) {
                // do something when get trip details success
                // access roam trip distance covered with roamTrip.getDistanceCovered
                // access roam trip route with roamTrip.getRoute
                // access roam trip duration with roamTrip.getDuration
                // access roam trip id with roamTrip.getTripId
            }

            @Override
            public void onFailure(RoamError roamError) {
                // do something when get trip details error
                // access roam error code with roamError.getCode()
                // access roam error message with roamError.getMessage()
            }
});

Trip v2 SDK Methods (Android)

Explore the Trips v2 SDK Methods for Android

Create Trip (Android)

Explore how to create a trip on Android with Trips v2.

To create a trip, you need to create an object for the trip and assign it with the RoamTrip() builder class. Below are the parameters and their descriptions for the trip object.

Parameter

Type

Description

Optional

metadata

JSONObject

A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

tripName

String

The name of the trip

tripDescription

String

The description for the trip

isLocal

boolean

Value determining if the trip is a local trip.

user

String

The user ID

Stops

List <RoamTripStops>

The list of stop object

When you create a trip, you can add stop locations which are nothing but locations where the user taking the trip will receive events for entry and exit. To create and assign stops to a trip, create objects for a single or multiple stops and assign them with the RoamTripStops() class. Below are the parameters and their descriptions for the stop object.

Parameter

Type

Description

Optional

metadata

JSONObject

A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

stopName

String

The stop name

stopDescription

String

The stop description

geometryRadius

Double

The stop radius

geometry

List<Double>

The coordinates list with longitude and latitude.

address

String

The stop address

Below is an example code for creating a trip with two stops. Let's create our stop objects.

JSONObject metadata = new JSONObject();
        metadata.put("Key", "value");
      
List<Double> geometry1 = new ArrayList<>();
        geometry1.add(23.5155215);
        geometry1.add(85.30614739);

List<Double> geometry2 = new ArrayList<>();
        geometry2.add(12.9716);
        geometry2.add(77.5946);

RoamTripStops stop1 = new RoamTripStops();
        stop1.setMetadata(metadata);
        stop1.setStopDescription("description");
        stop1.setStopName("name");
        stop1.setAddress("address");
        stop1.setGeometryRadius(100.0);
        stop1.setGeometry(geometry1);

 RoamTripStops stop2 =new RoamTripStops();
        stop2.setStopId("");
        stop2.setMetadata(metadata);
        stop2.setStopDescription("description");
        stop2.setStopName("name");
        stop2.setAddress("address");
        stop2.setGeometryRadius(600.0);
        stop2.setGeometry(geometry2);

 List<RoamTripStops> stop = new ArrayList<>();
        stop.add(stop1);
        stop.add(stop2);

   val metadata = JSONObject()
        metadata.put("Key", "value")

        val geometry1: MutableList<Double> = ArrayList()
        geometry1.add(23.5155215)
        geometry1.add(85.30614739)

        val geometry2: MutableList<Double> = ArrayList()
        geometry2.add(12.9716)
        geometry2.add(77.5946)

        val stop1 = RoamTripStops()
        stop1.setMetadata(metadata)
        stop1.setStopDescription("description")
        stop1.setStopName("name")
        stop1.setAddress("address")
        stop1.setGeometryRadius(100.0)
        stop1.setGeometry(geometry1)

        val stop2 = RoamTripStops()
        stop2.setStopId("")
        stop2.setMetadata(metadata)
        stop2.setStopDescription("description")
        stop2.setStopName("name")
        stop2.setAddress("address")
        stop2.setGeometryRadius(600.0)
        stop2.setGeometry(geometry2)

        val stop: MutableList<RoamTripStops> = ArrayList()
        stop.add(stop1)
        stop.add(stop2)

Now, let's create an object for the trip and update the parameters along with stop which was created above.

RoamTrip trip = new RoamTrip.Builder()
                .setUserId("userId")
                .setMetadata(metadata)
                .setTripDescription("description")
                .setTripName("name")
                .setIsLocal(true)
                .setStop(stop)
                .build();

val trip: RoamTrip? = RoamTrip.Builder()
            .setUserId("userId")
            .setMetadata(metadata)
            .setTripDescription("description")
            .setTripName("name")
            .setIsLocal(true)
            .setStop(stop)
            .build()

Now that the trip and stop objects are created, let's create the trip with Roam.createTrip() method.

Roam.createTrip(trip, new RoamTripCallback() {
            @Override
            public void onSuccess(RoamTripResponse response) {
              //get trip details
            }

            @Override
            public void onError(Error error) {
               //get error details
            }
        });

Roam.createTrip(trip, object : RoamTripCallback {
            override fun onSuccess(response: RoamTripResponse) {
                //get trip details
            }

            override fun onError(error: Error?) {
                //get error details
            }

        })t

The list of responses and error parameters are given below with their descriptions.

To access the status parameters:

Parameter

Type

Description

response.getCode()

Integer

The response code of the method.

response.getMessage()

String

The response message of the method.

To access the trip response:

Parameter

Type

Description

getTripDetails().getTripId()

String

Unique identifier for the object.

getTripDetails().getMetadata()

Object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

getTripDetails().getTripName()

String

The name of the trip

getTripDetails().getTripDescription()

String

The trip’s description

getTripDetails().getTripState()

String

The current state of the trip is either created, started, or ended.

getTripDetails().getIsLocal()

boolean

Value determining if the trip is a local trip.

getTripDetails().getTotalDistance()

double

The total distance covered by the user for this trip.

getTripDetails().getTotalDuration()

double

The total duration taken by the user for this trip.

getTripDetails().getTotalElevationGain()

double

The total elevation gain covered by the user for this trip.

getTripDetails().createdAt()

String

Timestamp of when the trip was created

getTripDetails().updatedAt()

String

Timestamp of when the trip was updated

getTripDetails().startedAt()

String

Timestamp of when the trip was started by the user

getTripDetails().endedAt()

String

Timestamp of when the trip was ended by the user

To access user details:

Parameter

Type

Description

getUser().getId()

String

Unique identifier for the object.

getUser().getMetadata()

Object

A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

getUser().getDescription()

String

User description

getUser().getName()

String

The user's full name

To access stop details:

Parameter

Type

Description

getStops().get(i).getStopName()

String

The stop name

getStops().get(i).getStopDescription()

String

The stop description

getStops().get(i).getMetadata()

Object

A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

getStops().get(i).getGeometryRadius()

double

The stop radius.

getStops().get(i).getGeometry()

Object

The coordinates list with longitude and latitude.

getStops().get(i).getArrivedAt()

String

The timestamp when the user arrived at the stop.

getStops().get(i).getDepartedAt()

String

The timestamp when the user departed from the stop.

getStops().get(i).getAddress()

String

The stop address .

To access error details:

Parameter

Type

Description

error.getErrorCode()

Integer

The error response code of the method.

error.getErrorMessage()

String

The error response message of the method.

error.getErrorDescription()

String

The error response description of the method.

error.getErrors().get(i).getMessage()

String

The message for error detail.

error.getErrors.get(i).getField()

String

The field for error detail.

Update Trip (Android)

Explore how to update a trip on Android with Trips v2.

The Update Trip method allows you to update your trip details at any point in time. However, you can update the stop locations as long as the trip has not started. You need to create a new object or update the existing trip, assign it with the RoamTrip() class and pass the trip object to Roam.updateTrip(trip).

Since the updateTrip method updates the existing trip, you need to pass the tripId to the trip object where the tripId is the unique identifier for your trip.

 Roam.updateTrip(trip, new RoamTripCallback() {
                    @Override
                    public void onSuccess(RoamTripResponse response) {
                       //get trip details
                    }

                    @Override
                    public void onError(Error error) {
                      //get error details
                    }
                });

 Roam.updateTrip(trip, object : RoamTripCallback {
            override fun onSuccess(response: RoamTripResponse) {
                //get trip details
            }

            override fun onError(error: Error?) {
                //get error details
            }
        })

The trip response and its parameters are similar to those of the createTrip() method.

There's no need to exclusively specify if the trip is local using a boolean value. The updateTrip() method will check that for you and update the trip details accordingly.

Start Quick Trip (Android)

Explore how to start a quick trip on Android with Trips v2.

A Quick Trip creates and starts a trip immediately with a single method. Creating a quick trip is similar to creating a trip.

Parameter

Type

Description

Optional

metadata

JSONObject

A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

tripName

String

Name of the trip

tripDescription

String

Trip description

isLocal

boolean

Value determining if the trip is a local trip.

Along with the above trip object, you need to pass an additional parameter for trackingMode which is optional and defaults to active tracking mode.

Roam.startTrip(trip, RoamTrackingMode.active, new RoamTripCallback() {
                    @Override
                    public void onSuccess(RoamTripResponse response) {
                       //get trip details
                    }

                    @Override
                    public void onError(Error error) {
                       //get error details
                    }
                });

 Roam.startTrip(trip, RoamTrackingMode.ACTIVE, object : RoamTripCallback {
            override fun onSuccess(response: RoamTripResponse) {
                //get trip details
            }

            override fun onError(error: Error?) {
                //get error details
            }
        })

To start a quick trip in custom tracking mode, refer to the following code snippet block.

RoamTrackingMode roamTrackingMode = new RoamTrackingMode.Builder(distanceFilter, stopDuration)
                        .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
                        .build();

Roam.startTrip(trip, roamTrackingMode, new RoamTripCallback() {
                    @Override
                    public void onSuccess(RoamTripResponse response) {
                       //get trip details
                    }

                    @Override
                    public void onError(Error error) {
                       //get error details
                    }
                });

val roamTrackingMode = RoamTrackingMode.Builder(distanceFilter, stopDuration)
            .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
            .build()

        Roam.startTrip(trip, roamTrackingMode, object : RoamTripCallback {
            override fun onSuccess(response: RoamTripResponse) {
                //get trip details
            }

            override fun onError(error: Error?) {
                //get error details
            }
        })

The list of responses and error parameters are given below with their descriptions.

To access the status parameters:

Parameter

Type

Description

response.getCode()

Integer

The response code of the method.

response.getMessage()

String

The response message of the method.

To access trip responses:

Parameter

Type

Description

getTripDetails().getTripId()

String

Unique identifier for the object.

getTripDetails().getMetadata()

Object

A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

getTripDetails().getTripName()

String

The trip name

getTripDetails().getTripDescription()

String

The trip’s description

getTripDetails().getTripState()

String

The current state of the trip is either created, started, or ended.

getTripDetails().getIsLocal()

boolean

The value determining if the trip is a local trip.

getTripDetails().getTotalDistance()

double

The total distance covered by the user for this trip.

getTripDetails().getTotalDuration()

double

The total duration taken by the user for this trip.

getTripDetails().getTotalElevationGain()

double

The total elevation gain covered by the user for this trip.

getTripDetails().createdAt()

String

Timestamp of when the trip was created

getTripDetails().updatedAt()

String

Timestamp of when the trip was updated

getTripDetails().startedAt()

String

Timestamp of when the trip was started by the user

getTripDetails().endedAt()

String

Timestamp of when the trip was ended by the user

To access user details:

Parameter

Type

Description

getUser().getId()

String

Unique identifier for the object.

getUser().getMetadata()

Object

A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

getUser().getDescription()

String

User description

getUser().getName()

String

The user's full name

To access error details:

Parameter

Type

Description

error.getErrorCode()

Integer

The error response code of the method.

error.getErrorMessage()

String

Error response message of the method.

error.getErrorDescription()

String

Error response description of the method.

error.getErrors().get(i).getMessage()

String

Message for error detail.

error.getErrors.get(i).getField()

String

The field for error detail.

Start Trip (Android)

Explore how to start a trip on Android with Trips v2.

The Start Trip method allows you to start a planned trip with the previously created tripID.

 Roam.startTrip("tripId", new RoamTripCallback() {
                            @Override
                            public void onSuccess(RoamTripResponse response) {
                               //get trip details
                            }

                            @Override
                            public void onError(Error error) {
                             //get error details  
                            }
                        });

 Roam.startTrip("tripId", object : RoamTripCallback {
            override fun onSuccess(response: RoamTripResponse?) {
                //get trip details
            }

            override fun onError(error: Error?) {
                //get error details
            }
        })

The trip response and its parameters are similar to those of the createTrip() method.

End Trip (Android)

Explore how to end a trip on Android with Trips v2.

the End Trip method allows you to end the trip with the previously created tripID. If you want to stop tracking, then you can pass stopTracking as true or false.

 Roam.endTrip("tripId",true, new RoamTripCallback() {
                            @Override
                            public void onSuccess(RoamTripResponse response) {
                               //get trip details
                            }

                            @Override
                            public void onError(Error error) {
                             //get error details  
                            }
                        });

 Roam.endTrip("tripId", true, object : RoamTripCallback {
            override fun onSuccess(response: RoamTripResponse) {
                //get trip details
            }

            override fun onError(error: Error?) {
                //get error details
            }
        })

The trip response and its parameters are similar to those of the createTrip method.

Pause Trip (Android)

Explore how to pause a trip on Android with Trips v2.

The pause trip method allows you to pause the trip with the previously created tripID.

The trip response and its parameters are similar to those of the createTrip method.

Resume Trip (Android)

Explore how to resume a trip on Android with Trips v2.

The Resume Trip method allows you to resume the trip with the previously paused tripID.

The trip response and its parameters are similar to those of the createTrip method.

Sync Trip (Android)

Explore how to sync a trip on Android with Trips v2.

Sync Trip allows you to sync a local trip to the server by using tripID.

You can access the sync trip response parameters below:

Get Trip (Android)

Explore how to get the details of a trip on Android with Trips v2.

To get the details of the trip anytime, you can use the Roam.getTrip("tripId") method by passing the tripID.

The trip response and its parameters are similar to those of the createTrip method.

There's no need to exclusively specify if the trip is local or not using a boolean value. The getTrip() method will check that for you and update the trip details accordingly.

Get Active Trips (Android)

Explore how to get a user's active trips on Android with Trips v2.

To get the users' active trips, you can use the Roam.getActiveTrips(isLocal) method where the value of isLocal is boolean. The value being true returns all the local trips and value being false, returns all active trips created on the server side.

The Get Active trips method returns all the trips in the form of a list. The parameters and responses are similar to those of the createTrip() method.

Get Trip Summary (Android)

Explore how to get the summary of a trip on Android with Trips v2.

To get a summary of the trip anytime, you can use the Roam.getTripSummary("tripId") method by passing the tripID.

The trip response and its parameters are similar to those of the createTrip() method.

You don't need to mention if the trip is local trip with a boolean value. The getTripSummary() method will check that for you and return the trip details accordingly.

Subscribe to Trip (Android)

Explore how to subscribe to a trip on Android with Trips v2.

You can subscribe to a trip using the tripID to get real-time trip data.

Once you subscribe to the trip, you will receive real time trip data in the listener method of RoamReceiver sub-class.

In order to subscribe to the trips with the listener method, you need to make sure the below is implemented.

Listeners are needed to consume the location data from the SDK itself. In order to enable listeners, ensure the following.

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

Then add the code to the receiver.

You can access the subscribed trip response parameters below:

You can also unsubscribe from the trip using its tripID.

Delete Trip (Android)

Explore how to delete a trip on Android with Trips v2.

You can delete the trip irrespective of any trip state. To delete the trip, you need to use the tripID with Roam.deleteTrip("tripId") method.

You can access the delete trip response parameters below:

Troubleshooting (iOS)

Troubleshooting documentation for iOS.

PRODUCTS

APIs

Quickstart (Android)

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,

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

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

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.1.20'
}

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

Using Manifest file Initialization:

Optional Parameter: Publish Key
- The publishKey parameter in the initialization method is now optional.
- If you've added your Roam publish key to your project's Manifest file, there's no need to pass the publishKey parameter during initialization.
Configure Your Manifest File:
- In your Manifest file, declare your Roam publish key as follows:
```
<meta-data
 android:name="com.roam.lib.sdk.PUBLISH_KEY"
 android:value="${ROAM_PUBLISH_KEY}" />
```
- Replace ${ROAM_PUBLISH_KEY} with your actual Roam publish key.
Using local.properties (Optional):
- Alternatively, you can use a local.properties file to feed the Roam publish key to the Manifest file.
- In your local.properties file, add the following line, replacing XXXXXXXXXXXXXX with your Roam publish key:
```
ROAM_PUBLISH_KEY = XXXXXXXXXXXXXX
```
- To get Roam publish key from local.properties to Manifest, user must have to add following code in build.gradle(app)
```
defaultConfig {
        Properties properties = new Properties()
        properties.load(project.rootProject.file('local.properties').newDataInputStream())
        manifestPlaceholders = [ROAM_PUBLISH_KEY: "${properties.getProperty('ROAM_PUBLISH_KEY')}"]

    }
```
Initialization Code:
- Initialize Roam SDK in your application class as follows:
- If the publish key is added to the Manifest file, the initialize method can be called without passing the publishable key.

Roam.initialize(this)

Roam.initialize(this);

By following these steps, you can seamlessly initialize Roam SDK using manifest file, simplifying the integration process and saving valuable development time.

Using Application class Initialization:

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")

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

Request Permission

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)
}

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

Roam.startTracking(TrackingMode, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })

Roam.startTracking(TrackingMode, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

Specify the tracking modes while you use the Roam.startTrackingmethod.

Tracking Modes

Adaptive 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

// active tracking
Roam.startTracking(RoamTrackingMode.ACTIVE, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })
// balanced tracking
Roam.startTracking(RoamTrackingMode.BALANCED, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })
// passive tracking
Roam.startTracking(RoamTrackingMode.PASSIVE, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })

// active tracking
Roam.startTracking(RoamTrackingMode.ACTIVE, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })
// balanced tracking
Roam.startTracking(RoamTrackingMode.BALANCED, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })
// passive tracking
Roam.startTracking(RoamTrackingMode.PASSIVE, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })

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:

// Define a custom tracking method with desired distance interval, stop duration and accuracy
val trackingMode = 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, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })

// 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, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

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:

// Define a custom tracking method with desired time interval and accuracy
val trackingMode = RoamTrackingMode.Builder(<TIME-INTERVAL-IN-SECONDS>)
            .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
            .build()
// Start the tracking with the above created custom tracking method
Roam.startTracking(trackingMode, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })

// 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, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

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.

Roam.stopTracking(object : TrackingCallback {
            override fun onSuccess(s: String) {
              //do something
            }
            override fun onError(roamError: RoamError) {
              //do something
            }
        })

Roam.stopTracking(new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

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

Add the code to the receiver.

class LocationReceiver: RoamReceiver() {
    override fun onLocationUpdated(context: Context?, roamLocations: MutableList<RoamLocation>?) {
        super.onLocationUpdated(context, roamLocations)
        // receive own location updates here
        // do something with location data using location
            for (roamLocation in roamLocations!!){
                roamLocation.activity
                roamLocation.recordedAt
                roamLocation.timezoneOffset
                roamLocation.metadata
                roamLocation.batteryStatus
                roamLocation.networkStatus
                roamLocation.location.latitude
                roamLocation.location.longitude
                roamLocation.location.bearing
                roamLocation.location.altitude
                roamLocation.location.accuracy
                roamLocation.location.speed
                roamLocation.location.provider
                roamLocation.location.time
                roamLocation.location.verticalAccuracyMeters
            }
    }

    override fun onError(context: Context?, roamError: RoamError?) {
        super.onError(context, roamError)
        // receive error message here
         roamError?.code
         roamError?.message
    }
}

public class LocationReceiver extends RoamReceiver {

    @Override
    public void onLocationUpdated(Context context, List<RoamLocation> roamLocations) {
        super.onLocationUpdated(context, roamLocations);
        // receive own location updates here
        // do something with location data using location
        for(RoamLocation roamLocation: roamLocations){
             roamLocation.getActivity();
             roamLocation.getRecordedAt();
             roamLocation.getTimezoneOffset();
             roamLocation.getMetadata();
             roamLocation.getBatteryStatus();
             roamLocation.getNetworkStatus();
             roamLocation.getLocation().getLatitude();
             roamLocation.getLocation().getLongitude();
             roamLocation.getLocation().getBearing();
             roamLocation.getLocation().getAltitude();
             roamLocation.getLocation().getAccuracy();
             roamLocation.getLocation().getSpeed();
             roamLocation.getLocation().getProvider();
             roamLocation.getLocation().getTime();
             roamLocation.getLocation().getVerticalAccuracyMeters();
        }
    }

    @Override
    public void onError(Context context, RoamError roamError) {
        super.onError(context, roamError);
        // receive error message here
         roamError.getCode();	
         roamError.getMessage();
    }
}

Batch Configuration

Batch configuration lets you control the number of location data updates being received in the location listener with the desired frequency and window.

Set Batch Configuration

As the name suggests, this method sets the configuration parameters.

The NetworkState.BOTH indicates the state in which the updates are to be received. It can either be set to online, offline, or both.
The batchCount indicates the size of the location batch.
The batchWindow indicates the time interval for every consecutive update (frequency of updates).

By default, the batch configuration values for both batch count and window are set to 1 and 0 respectively.

Roam.setBatchReceiverConfig(
    NetworkState.BOTH,
    batchCount,
    batchWindow,
    object : RoamBatchReceiverCallback {
        override fun onSuccess(list: List<BatchReceiverConfig>) {
            list[i].networkState
            list[i].batchCount
            list[i].batchWindow
        }
        override fun onFailure(roamError: RoamError) {
            roamError.code
            roamError.message
        }
    })

Roam.setBatchReceiverConfig(NetworkState.BOTH, batchCount,
batchWindow, new RoamBatchReceiverCallback() {
@Override
           public void onSuccess(List<BatchReceiverConfig> batchReceiverConfig) {
                 batchReceiverConfig.get(i).getNetworkState();
                 batchReceiverConfig.get(i).getBatchCount();
                 batchReceiverConfig.get(i).getBatchWindow();
}
@Override
           public void onFailure(RoamError error) {
              error.getMessage();
              error.getCode();
} });

Consider the following call,

Roam.setBatchConfig("NetworkState.Both", 5 , 60)

Success Callback - We receive a list of BatchReceiveConfig objects.

Example response:

[{"batchCount":5,"batchWindow":10,"networkState":"OFFLINE"}, {"batchCount":5,"batchWindow":10,"networkState":"ONLINE"}]

Error Callback: We receive a RoamError object in the error callback.

The available details to get from the RoamError object are: error.getMessage() and error.getCode()

Get Batch Configuration

The get receiver config method allows the user to get the current batch configuration for the location listener.

Roam.getBatchReceiverConfig(object : RoamBatchReceiverCallback {
    override fun onSuccess(list: List<BatchReceiverConfig>) {
        list[i].networkState
        list[i].batchCount
        list[i].batchWindow
    }
    override fun onFailure(roamError: RoamError) {
        roamError.code
        roamError.message
    }
})

Roam.getBatchReceiverConfig(new RoamBatchReceiverCallback() {

@Override
           public void onSuccess(List<BatchReceiverConfig> batchReceiverConfig) {
                 batchReceiverConfig.get(i).getNetworkState();
                 batchReceiverConfig.get(i).getBatchCount();
                 batchReceiverConfig.get(i).getBatchWindow();
}
@Override
           public void onFailure(RoamError error) {
              error.getMessage();
              error.getCode();
} });

The response for the above code is the same as that of the Set Receiver Config method.

Reset Batch Configuration

The Reset Batch Configuration method allows the user to reset the batch config for the location listener.

Roam.resetBatchReceiverConfig(object : RoamBatchReceiverCallback {
    override fun onSuccess(list: List<BatchReceiverConfig>) {
        list[i].networkState
        list[i].batchCount
        list[i].batchWindow
    }
    override fun onFailure(roamError: RoamError) {
        roamError.code
        roamError.message
    }
})

Roam.resetBatchReceiverConfig(new RoamBatchReceiverCallback() {
@Override
           public void onSuccess(List<BatchReceiverConfig> batchReceiverConfig) {
                 batchReceiverConfig.get(i).getNetworkState();
                 batchReceiverConfig.get(i).getBatchCount();
                 batchReceiverConfig.get(i).getBatchWindow();
}
@Override
           public void onFailure(RoamError error) {
              error.getMessage();
              error.getCode();
} });Roam.resetBatchReceiverConfig(object : RoamBatchReceiverCallback {
    override fun onSuccess(list: List<BatchReceiverConfig>) {
        list[i].networkState
        list[i].batchCount
        list[i].batchWindow
    }
    override fun onFailure(roamError: RoamError) {
        roamError.code
        roamError.message
    }
})

Pub/Sub Locations (Android)

Explore how to publish and subscribe locations for Android.

Creating Users

Adding metadata to users is optional and you can pass null while creating users to ignore that field.

You can always set or update user descriptions and meta-data later using the code below.

// update user with meta-data and description
// Declare meta-data as dictionary
// Description as string
val metadata = JSONObject() 
metadata.put("key", "value") 
Roam.setDescription("SET-USER-DESCRIPTION-HERE", metadata)

// update user with meta-data and description
// Declare meta-data as dictionary
// Description as string
JSONObject metadata = new JSONObject(); 
metadata.put("key", "value"); 
Roam.setDescription("SET-USER-DESCRIPTION-HERE", metadata);

Get User

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

Roam.getUser("ROAM-USER-ID", object : RoamCallback {
      override fun 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 fun onFailure(roamError: RoamError) {
        // Access error code & message below
        // roamError.getCode()
        // roamError.getMessage()
      }
})

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();
            }
        });

Location Tracking

To publish and subscribe to location data, startSelfTracking methods have to be changed to startTracking

Start Tracking

Roam.startTracking(TrackingMode, object:TrackingCallback(){
            override fun onSuccess(s: String?) {
                //do something
            }

            override fun onError(roamError: RoamError?) {
                //do something
            }
        })

Roam.startTracking(TrackingMode, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

Specify the tracking mode while you use the startTracking method Roam.startTracking

Tracking Modes

// active tracking
Roam.startTracking(RoamTrackingMode.ACTIVE, object:TrackingCallback(){
            override fun onSuccess(s: String?) {
                //do something
            }

            override fun onError(roamError: RoamError?) {
                //do something
            }
        })
// balanced tracking
Roam.startTracking(RoamTrackingMode.BALANCED, object:TrackingCallback(){
            override fun onSuccess(s: String?) {
                //do something
            }

            override fun onError(roamError: RoamError?) {
                //do something
            }
        })
// passive tracking
Roam.startTracking(RoamTrackingMode.PASSIVE, object:TrackingCallback(){
            override fun onSuccess(s: String?) {
                //do something
            }

            override fun onError(roamError: RoamError?) {
                //do something
            }
        })

// active tracking
Roam.startTracking(RoamTrackingMode.ACTIVE, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });
// balanced tracking
Roam.startTracking(RoamTrackingMode.BALANCED, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });
// passive tracking
Roam.startTracking(RoamTrackingMode.PASSIVE, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

Custom Tracking Modes

Our SDK also provides a custom tracking mode that allows you to customize and build your own tracking modes.

Distance between location updates example code:

// Define a custom tracking method with desired distance interval, stop duration and accuracy
val trackingMode = 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, object:TrackingCallback(){
            override fun onSuccess(s: String?) {
                //do something
            }

            override fun onError(roamError: RoamError?) {
                //do something
            }
        })

// 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, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

Time between location updates example code:

// Define a custom tracking method with desired time interval and accuracy
val trackingMode = RoamTrackingMode.Builder(<TIME-INTERVAL-IN-SECONDS>)
                  .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
                  .build()
// Start the tracking with the above created custom tracking method
Roam.startTracking(trackingMode, object:TrackingCallback(){
            override fun onSuccess(s: String?) {
                //do something
            }

            override fun onError(roamError: RoamError?) {
                //do something
            }
        })

// 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, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

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.

Roam.stopTracking(object : TrackingCallback {
            override fun onSuccess(s: String) {
              //do something
            }
            override fun onError(roamError: RoamError) {
              //do something
            }
        })

Roam.stopTracking(new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

Publish Locations

Publishing will help publish location data that will be stored in our database and sent to Roam servers for further processing.

Location data will be published and sent to the Roam servers for further processing. The data will be saved on our database servers.

val locationData = RoamPublish.Builder().build()
Roam.publishAndSave(locationData, object : PublishCallback {
            override fun onSuccess(s: String) {
                //do something
            }
            override fun onError(roamError: RoamError) {
                //do something
            }
        })

RoamPublish locationData = new RoamPublish.Builder().build();
Roam.publishAndSave(locationData, new PublishCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

You can now send custom meta-data json values along with location data in publishAndSavemethod.

val data = JSONObject()
data.put("Key", "Value")
val roamPublish = RoamPublish.Builder()
            .metadata(data)
            .build()
Roam.publishAndSave(roamPublish, object : PublishCallback {
            override fun onSuccess(s: String) {
                //do something
            }
            override fun onError(roamError: RoamError) {
                //do something
            }
        })

JSONObject data = new JSONObject();
data.put("Key", "Value");
RoamPublish roamPublish = new RoamPublish.Builder()
                    .metadata(data)
                    .build();
Roam.publishAndSave(roamPublish, new PublishCallback() {
            @Override
            public void onSuccess(String s) {
               //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

To stop publishing locations,

Roam.stopPublishing(object : PublishCallback {
            override fun onSuccess(s: String) {
                //do something
            }
            override fun onError(roamError: RoamError) {
                //do something
            }
        })

Roam.stopPublishing(new PublishCallback() {
            @Override
            public void onSuccess(String s) {
                //do something
            }

            @Override
            public void onError(RoamError roamError) {
                //do something
            }
        });

Now that you have enabled the location listener, use the below method to subscribe to your own or other user's location updates and events.

Roam.subscribe(TYPE, "ROAM-USER-ID", object : SubscribeCallback {
            override fun onSuccess(s: String, s1: String) {
                //do something
            }
            override fun onError(roamError: RoamError) {
                //do something
            }
        })

Roam.subscribe(TYPE, "USER-ID", new SubscribeCallback() {
            @Override
            public void onSuccess(String s, String s1) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

UnSubscribe

Roam.unSubscribe(TYPE, "ROAM-USER-ID", object : SubscribeCallback {
            override fun onSuccess(s: String, s1: String) {
                //do something
            }
            override fun onError(roamError: RoamError) {
                //do something
            }
        })

Roam.unSubscribe(TYPE, "ROAM-USER-ID", new SubscribeCallback() {
            @Override
            public void onSuccess(String s, String s1) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

You can pass an empty user_id which is an optional field from v0.0.14 to unsubscribe from all the users.

Location Listener

Before adding listeners for locations and other data, we need to toggle the listener flags for the user in order to get the data.

Roam.toggleListener(locations, events, object : RoamCallback {
    override fun onSuccess(roamUser: RoamUser) {
        // do something when toggle listener success
        // access location listener status with roamUser.getLocationListenerStatus()
        // access event listener status with roamUser.getEventListenerStatus()
    }

    override fun onFailure(roamError: RoamError) {
        // do something when toggle listener failure
    }
})

Roam.toggleListener(true, true, 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();
            }
        });

You can also get the current status of listeners with the below method.

Roam.getListenerStatus(object : RoamCallback {
    override fun onSuccess(roamUser: RoamUser) {
        // do something when get listener status success
        // get location listener status with roamUser.getLocationListenerStatus
        // get event listener status with roamUser.getEventListenerStatus
    }
    override fun onFailure(roamError: RoamError) {
        // do something when get listener status failure
    }
})

Roam.getListenerStatus(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();
            }
      });

Toggle Events

To listen to events on the server-side, you should enable events for the user using the method below.

Roam.toggleEvents(geofence, trip, location, movingGeofence, object : RoamCallback {
    override fun onSuccess(roamUser: RoamUser) {
        // do something when toggle events success
        // access location event status with roamUser.getLocationEvents()
        // access geofence event status with roamUser.getGeofenceEvents()
        // access trip events status with roamUser.getTripsEvents()
        // get moving geofence event status with roamUser.getMovingGeofenceEvents()
    }

    override fun onFailure(error: roamError) {
        // do something when toggle events failure
    }

Roam.toggleEvents(true, true, true, true, 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();
            }
        });

Location Listener

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

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

public class LocationReceiver : RoamReceiver() {
    override fun onLocationUpdated(context: Context, roamLocations: MutableList<RoamLocation>) {
        // receive own location updates here
        // do something with location data using location
    }

    override fun onLocationReceived(context: Context, roamLocationReceived: RoamLocationReceived) {
        // receive other user's location updates here
        // do something with location
    }
    
    override fun onEventReceived(context: Context, roamEvent: RoamEvent) {
        //access event data here
    }

    override fun onReceiveTripStatus(context: Context, listener:List<TripStatusListener>) {
        // receive real time trip status here
        // do something with trip status data    
    }

    override fun onError(context: Context, roamError: RoamError) {
        //access error data here
    }
}

public class LocationReceiver extends RoamReceiver {

    @Override
    public void onLocationUpdated(Context context, List<RoamLocation> roamLocations) {
        // receive own location updates here
		    // do something with location data using location
    }

    @Override
    public void onLocationReceived(Context context, RoamLocationReceived roamLocationReceived) {
        // receive other user's location updates here
    		// do something with location
    }

    @Override
    public void onEventReceived(Context context, RoamEvent roamEvent) {
    		//access event data here
    }

    @Override
    public void onReceiveTripStatus(Context context,List<TripStatusListener> listener) {
                // receive real time trip status here
                // do something with trip status data    
    }

    @Override
    public void onError(Context context, RoamError roamError) {
         //access error data here
    }
}

Quickstart (iOS)

The Roam iOS SDK makes it quick and easy to build a location tracker for your iOS app. We provide powerful and customizable tracking modes and features that can be used to collect your users’ location

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 iOS app to the project.
You need the SDK_KEY (available in your project settings) to initialize the SDK.

You’re now ready to integrate the SDK into your iOS application.

The Roam iOS SDK requires Xcode 10.0 or later and is compatible with apps targeting iOS version 10 and above.

Run the example application

The Roam Example repository on GitHub includes example apps that demonstrate the use of the v3 Roam SDK for iOS.

See Swift's example app in Example/.

To run an example app, clone this repository, add your publishable YOUR-PUBLISHABLE-KEY key in AppDelegate.swift, and build the app.

Make sure the bundle_id is the same as the one registered on our Roam Playground dashboard.

Xcode Setup

To integrate the Roam SDK, you need a Roam account.

Go to Xcode > File > New Project
Configure the information property list file Info.plist with an XML snippet that contains data about your app. You need to add strings for NSLocationWhenInUseUsageDescription in the Info.plist file to prompt the user during location permissions for foreground location tracking. For background location tracking, you also need to add a string for NSLocationAlwaysUsageDescription and NSLocationAlwaysAndWhenInUseUsageDescription in the same Info.plist file.
```
<key>NSLocationWhenInUseUsageDescription</key>
<string>Add description for foreground only location usage.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Add description for background location usage. iOS 10 and below"</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Add description for background location usage. iOS 11 and above</string>
```

Next, you need to enableBackground fetch and Location updates under Project Setting > Capabilities > Background Modes.

SDK Installation

There are several ways to integrate the Roam Mobile SDK for iOS into your own project:

Swift Package Manager
CocoaPods
Carthage (Will be added soon)
Dynamic Frameworks

Swift Package Manager Installation

Swift Package Manager is distributed with Xcode. To start adding the AWS SDK to your iOS project, open your project in Xcode and select File > Swift Packages > Add Package Dependency.

Enter the URL for the Roam SDK for iOS Swift Package Manager GitHub repo (https://github.com/roam-ai/roam-ios) into the search bar and click Next.

You'll see the repository rules for which version of the SDK you want the Swift Package Manager to install. Choose the first rule, Version, and select Up to Next Minor as it will use the latest compatible version of the dependency that can be detected from the main branch, then click Next.

Select roam-ios, then click Finish.

You can always go back and modify which SPM packages are included in your project by opening the Swift Packages tab for your project: Click on the Project file in the Xcode navigator, then click on your project's icon, then select the Swift Packages tab.

CocoaPods Installation

Follow the steps below to add the SDK to the project using CocoaPods. Add the below to the Podfile

pod 'roam-ios'

Then run pod install.

This will add the Roam SDK and its dependencies to your project. The Roam SDK depends on CoreLocation, AWSMobileClient and AWSIoT for fetching locations and its transmission to our servers. The SDK supports iOS 10 and above.

Manual Installation

If you’re not familiar with using Cocoapods or prefer manual installation, we’ve added a ZIP file to the SDK. Use this link to download the Roam.zip file.

Unzip the file and add the Roam Roam.framework to your Xcode project by dragging the file into your Project Navigator.

You can do this by selecting the project file in the navigator on the left side of the Xcode window, and then navigating to the Linked Frameworks and Libraries section. From there, click the “+” button to add the Roam framework. You will also want to add the following frameworks from this link.

AWSAuthCore.xcframework
AWSCognitoIdentityProvider.xcframework
AWSCognitoIdentityProviderASF.xcframework
AWSCore.xcframework
AWSIoT.xcframework
AWSMobileClientXCF.xcframework

Make sure the the added frameworks under Linked Frameworks and Libraries section are selected as Embed & Sign

Initialize SDK

Roam SDK offers a flexible method of initialization, allowing developers to seamlessly integrate our services into their applications. With our latest update, we've introduced a new initialization approach using property list files (plist). This method provides an effortless way to set up your Roam SDK without the need for additional code.

Using Property List (plist) Initialization:

Optional Parameter: Publish Key
- The publishKey parameter in the initialization method is now optional.
- If you've added your Roam publish key to your project's .plist file, there's no need to pass the publishKey parameter during initialization.
Configure Your .plist File:
- In your info.plist file, declare your Roam publish key as follows:
```
<key>ROAM_PUBLISH_KEY</key>
<string>$(ROAM_PUBLISH_KEY)</string>
```
- Replace "$(ROAM_PUBLISH_KEY)" with your actual Roam publish key.
Using XCConfig File (Optional):
- Alternatively, you can use an XCConfig file to feed the Roam publish key to the plist file.
- In your XCConfig file, add the following line, replacing XXXXXXXXXXXXXX with your Roam publish key:
```
ROAM_PUBLISH_KEY = XXXXXXXXXXXXXX
```
Initialization Code:
- Initialize Roam SDK in your application as follows:
```
Roam.initialize("")
// OR
Roam.initialize(nil)
```
- If the publish key is added to the plist, the initialize method can be called without passing any parameters.

By following these steps, you can seamlessly initialize Roam SDK using property list files, simplifying the integration process and saving valuable development time.

Using AppDelegate Initialization:

Add the following code to AppDelegate file. This code imports the SDK and allows the SDK to use other methods.

import Roam

After import, add the below code underapplication(_:didFinishLaunchingWithOptions:) in your AppDelegate file. The SDK must be initialized before calling any of the other SDK methods using your project's publishable key.

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

Request Permissions

Before you start location tracking, you need to get permission from the user for your application to access locations.

Import CoreLocation at the top of the AppDelegate file.
```
import CoreLocation
```
Make the below class declaration for Location Manager and add this line before the return statement in application(_:didFinishLaunchingWithOptions:) With this line, you ask users to allow the app to access location data both in the background and the foreground.
```
let locationManager = CLLocationManager()
locationManager.requestLocation()
```

Location Tracking

Start Tracking

Roam.startTracking(TrackingMode){ status, error in

}

Use one of the tracking modes while you use the Roam.startTracking method.

Stop Tracking

To stop the tracking use the below method.

Roam.stopTracking(){ status, error in

}

Tracking Modes

Adaptive Tracking

Roam has three default tracking modes along with a custom version. They are different based on the frequency of location updates and battery consumption. The higher the frequency, the higher the battery consumption.

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

//active tracking
Roam.startTracking(RoamTrackingMode.active){ status, error in

}
// balanced tracking
Roam.startTracking(RoamTrackingMode.balanced){ status, error in

}
// passive tracking
Roam.startTracking(RoamTrackingMode.passive){ status, error in

}

Distance Interval Tracking

The SDK also provides a custom tracking mode which allows you to customize and build your own tracking mode as per your requirement.

Type

Unit

Unit Range

Distance Interval

Meters

1m ~ 2500m

Distance between location updates example code:

// Define a custom tracking method
let distanceTrackingMethod = RoamTrackingCustomMethods()

// Update the settings for the created method as per need
distanceTrackingMethod.activityType = .fitness
distanceTrackingMethod.pausesLocationUpdatesAutomatically = true
distanceTrackingMethod.showsBackgroundLocationIndicator = true
distanceTrackingMethod.useSignificant = false
distanceTrackingMethod.useRegionMonitoring = false
distanceTrackingMethod.useVisits = false
distanceTrackingMethod.accuracyFilter = 10
distanceTrackingMethod.desiredAccuracy = .kCLLocationAccuracyNearestTenMeters

// Update the distance intervel as per the use case in meters
distanceTrackingMethod.distanceFilter = 10

// Start the tracking with the above created custom tracking method
Roam.startTracking(.custom, options: distanceTrackingMethod){ status, error in

}

Time Interval Tracking

Type

Unit

Unit Range

Time Interval

seconds

1s - 10000s

Time between location updates example code:

// Define a custom tracking method
let timeTrackingMethod = RoamTrackingCustomMethods()

// Update the settings for the created method as per need
timeTrackingMethod.activityType = .fitness
timeTrackingMethod.pausesLocationUpdatesAutomatically = true
timeTrackingMethod.showsBackgroundLocationIndicator = true
timeTrackingMethod.useSignificant = false
timeTrackingMethod.useRegionMonitoring = false
timeTrackingMethod.useVisits = false
timeTrackingMethod.accuracyFilter = 10
timeTrackingMethod.desiredAccuracy = .kCLLocationAccuracyNearestTenMeters

// Update the time intervel as per the use case in seconds
timeTrackingMethod.updateInterval = 10

// Start the tracking with the above created custom tracking method
Roam.startTracking(.custom, options: timeTrackingMethod){ status, error in

}

Location Listener

To listen to location updates, create a class that implements RoamDeleagate and then call Roam.delegate.

Set your RoamDeleagate in a code path that will be initialized and executed in the background. For example, make your AppDelegate implement RoamDeleagate, not a ViewController. AppDelegate will be initialized in the background, whereas a ViewController may not be.

Note: In the case of tracking without user session ie. self-ttracking, 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.

import UIKit
import Roam
import CoreLocation

@main
class AppDelegate: UIResponder, UIApplicationDelegate, RoamDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Roam.delegate = self
        Roam.initialize("YOUR-SDK-KEY-GOES-HERE")
        return true
    }
    func didUpdateLocation(_ location: RoamLocation) {
        // Do something with the user location
        // location.userId
        // location.activity 
        // location.timezoneOffset  
        // location.recordedAt  
        // location.batteryRemaining
        // location.networkStatus 
        // location.metaData 
        // location.location.speed 
        // location.location.horizontalAccuracy
        // location.location.verticalAccuracy 
        // location.location.altitude  
        // location.location.course       
        // location.location.coordinate.latitude
        // location.location.coordinate.longitude 
    }

Batch Configuration

Batch configuration lets you control the number of location data updates being received in the location listener with the desired frequency and window.

Set Batch Configuration

As the name suggests, this method sets the configuration parameters.

The networkState indicates the state in which the updates are to be received. It can either be set to online, offline, or both.
The batchCount indicates the size of the location batch.
The batchWindow indicates the time interval for every consecutive update (frequency of updates).

By default, the batch configuration values for both batch count and window are set to 1 and 0 respectively.

// let networkState:RoamNetworkState = .Both
// batchCount: number of location updated
// batchWindow : frequency of location updates.
Roam.setBatchReceiverConfig(networkState: networkState, batchCount: batchCount, 
batchWindow: batchWindow) { config, error in
      // error?.code
      // error?.message
                                                                                       
               
      // config?.batchCount
      // config?.batchWindow
      // config?.networkState
 }

[Roam setBatchReceiverConfigWithNetworkState: networkState batchCount:batchCount 
batchWindow:batchWindow handler:^(RoamBatchConfig * config, RoamError * error) {
      // error?.code
      // error?.message
                                                                                       
               
      // config?.batchCount
      // config?.batchWindow
      // config?.networkState
  }];

Consider the following call,

Roam.setBatchConfig("networkState.Both", 5 , 60)

Success Callback - We receive a list of BatchReceiveConfig objects.

Example response:

[{"batchCount":5,"batchWindow":10,"networkState":"offline"}, {"batchCount":5,"batchWindow":10,"networkState":"online"}]

Error Callback: We receive a RoamError object in the error callback.

The available details to get from the RoamError object are: error.getMessage() and error.getCode()

Get Batch Configuration

The get receiver config method allows the user to get the current batch configuration for the location listener.

Roam.getBatchReceiverConfig { config, error in
      // error?.code
      // error?.message
                                                                                       
               
      // config?.batchCount
      // config?.batchWindow
      // config?.networkState
 }swif

[Roam getBatchReceiverConfigWithHandler:^(RoamBatchConfig * config, RoamError * error) 
{
      // error?.code
      // error?.message
                                                                                       
               
      // config?.batchCount
      // config?.batchWindow
      // config?.networkState
}];

obj

Reset Batch Configuration

The Reset Batch Configuration method allows the user to reset the batch config for the location listener.

Roam.resetBatchReceiverConfig { config, error in
      // error?.code
      // error?.message
                                                                                       
               
      // config?.batchCount
      // config?.batchWindow
      // config?.networkState
 }

[Roam resetBatchReceiverConfigHandler:^(RoamBatchConfig * config, RoamError * error) 
{
      // error?.code
      // error?.message
                                                                                       
               
      // config?.batchCount
      // config?.batchWindow
      // config?.networkState
}];

Changelog (Android)

Keep yourself updated on any Android changes.

0.1.23 - (Dec 20, 2023)

We're excited to introduce Roam Android SDK version 0.1.23, focusing on refining our location filters to improve accuracy during location tracking. In this update, we've made the following improvement:

Enhanced Location Filtering: We've refined our location filters to effectively discard drifts and noises during location tracking. This enhancement aims to improve the accuracy and reliability of location data, ensuring a more precise representation of user movement.

These improvements are geared towards providing a more accurate and dependable location tracking experience for developers and users. We're dedicated to enhancing your tracking capabilities and ensuring a smoother operational experience. Should you have any inquiries or feedback, our support team is readily available to assist you.

0.1.22 - (Dec 08, 2023)

We're excited to introduce Roam Android SDK version 0.1.22, focusing on refining our location filters to improve accuracy during location tracking. In this update, we've made the following improvement:

Enhanced Location Filtering: We've refined our location filters to effectively discard drifts and noises during location tracking. This enhancement aims to improve the accuracy and reliability of location data, ensuring a more precise representation of user movement.

0.1.21 - (Oct 27, 2023)

We're thrilled to present Roam Android SDK version 0.1.21, focusing on bolstering our security module. In this update, we've made significant improvements to enhance the security module of location tracking. Here's what's new:

Efficient Spoofed Location Detection: Our security algorithm has been refined to efficiently discard spoofed locations during the initial location fix. This enhancement ensures that only genuine and accurate location data is captured, enhancing the authenticity of the information gathered.
Addressing False Negatives: We've tackled false negatives during location tracking, ensuring that true locations are not mistakenly identified as spoofed locations. This refinement enhances the precision of location tracking, providing you with reliable and accurate data.

These security enhancements are designed to safeguard your data and ensure the integrity of the location information collected by the Roam Android SDK. Your security is our priority, and we're committed to providing you with a secure and trustworthy experience. If you have any questions, concerns, or feedback, our support team is always here to assist you.

0.1.20 - (Sep 30, 2023)

We are thrilled to introduce Roam Android SDK version 0.1.20, a significant step forward in enhancing your tracking experience. Here's what's new:

New Callbacks for Enhanced Control: With added success and error callbacks to methods like startTracking, stopTracking, subscribe, unSubscribe, publishAndSave, and stopPublishing, you now have precise control and real-time feedback for every SDK action.
Extended Security Checks: We've expanded the toggleSecurity() method with two vital parameters. Now, you can check for connected external accessories and Bluetooth status, bolstering security measures for your application. Your feedback has played a pivotal role in shaping these enhancements. Should you have any questions, encounter issues, or want to share your experiences, our dedicated support team is here to assist you.

0.1.19 - (Aug 29, 2023)

We're excited to announce the latest release of the Roam Android SDK, version 0.1.19. This update brings a significant enhancement that contributes to heightened security and user control. Read on to discover the key highlights of this release:

New Feature: Motion Detection Security With Roam Android SDK v0.1.19, we introduce an innovative security feature—Motion Detection. This cutting-edge capability adds an extra layer of protection to your application's tracking experience. By enabling the verifyMotion parameter in the toggleSecurity() method, developers can now leverage motion patterns to enhance security. This empowers you to monitor and respond to unusual motion activities, ensuring a safer and more reliable tracking environment. Your feedback and insights have been instrumental in shaping the Roam Android SDK, and we're grateful for your ongoing support. If you have any questions, suggestions, or need assistance, please don't hesitate to contact our support team. As we strive to continually refine and enhance the SDK, look forward to more updates on the horizon.

0.1.18 - (Aug 23, 2023)

We're pleased to unveil Roam Android SDK version 0.1.18, showcasing an exciting new feature that enhances security and user control. Here's an overview of the latest updates:

New Security Module: Roam In this release, we introduce the Roam Security Module, a powerful addition to the SDK's arsenal. With the Roam module, developers now have access to the toggleSecurity() method, a versatile tool that allows the seamless activation and deactivation of advanced security mechanisms. Prioritizing data security is vital, and the Roam Security Module empowers developers to safeguard sensitive information more effectively.

Your feedback and insights have been instrumental in shaping the Roam Android SDK, and we're grateful for your ongoing support. If you have any questions, suggestions, or need assistance, please don't hesitate to contact our support team. As we strive to continually refine and enhance the SDK, look forward to more updates on the horizon.

0.1.17 - (Jul 3, 2023)

Added a new feature to get publish key from local.properties gradle file.
Fixed order of callbacks for create and get user methods and MQTT connection.

0.1.16 - (Jun 14, 2023)

Added stationary duration for all tracking modes except time base.

0.1.15 - (Jun 7, 2023)

Fixed noise and duplicate locations update.
Improved location accuracy.

0.1.14 - (May 17, 2023)

Added post notification support for android 13.
Removed work manager concept from SDK.

0.1.13 - (Mar 23, 2023)

Fixed work manager dependency version for react native SDK support.

0.1.12 - (Mar 16, 2023)

Fixed dynamic distance filter logic.
Fixed location update gap in time base tracking.
Added noise filter in time base tracking.

0.1.11 - (Feb 24, 2023)

Fixed batch location update issue.
Fixed trip sync issue.
Fixed multiple location update and speed inconsistent issue.

0.0.36 - (Feb 22, 2023)

Fixed multiple callback issue for trip methods.

0.1.10 - (Feb 10, 2023)

Added activity recognition to reduce battery consumption for default tracking modes.

0.1.9 - (Jan 20, 2023)

Added basic ingest publish topic for aws cost optimisation.

0.1.8 - (Jan 12, 2023)

Fixed deprecated code and time out error for get current location method.

0.0.35 - (Jan 5, 2023)

Fixed deprecated code and time out error for get current location method.

0.1.7 - (Dec 24, 2022)

Fixed get current location method.

0.1.6 - (Dec 16, 2022)

Removed isTripSynced method (no longer required).
Fixed updateCurrentLocation method, RoamPublish param can be null.
Fixed getActiveTrip method, if isLocal is true then get offline trips in response and vice-versa.
Fixed getActiveTrip method, trip stops point should be in response.
Fixed updateTrip method, isLocal param should not be required to update a trip.
Added SDK installation support for android 13.

0.0.34 - (Dec 13, 2022)

Added hourly location count feature.
Fixed the Roam SDK installation support for android 13.

0.1.5 - (Dec 1, 2022)

Added magnetic bearing support.
Added meta data support for setDescription method.
Added tracking config feature.
Added app service class parameter to setForegroundNotification method.

0.0.33 - (Nov 24, 2022)

Added magnetic bearing feature in SDK.

0.0.32 - (Nov 4, 2022)

Added metadata support for the setDescription() method.

0.0.31 - (Oct 14, 2022)

Added custom configuration support for Roam.initialize() method .

0.1.4 - (Oct 11, 2022)

Fixed the noise location update for distance-based tracking and stationary location update.

0.0.30 - (Sept 22, 2022)

Fixed the execution order of MQTT connection callback and createUser/getUser method's callback.

0.0.29 - (Sept 13, 2022)

Fixed location update gap in stationary location update.
Fixed location update when the device gets restarted.
Fixed tracking config logic for time base tracking.

0.1.3 - (Aug 26, 2022)

Added:

There should be a locations count field.
Batch update support for the trip listener.
Batch update support for location listener.
Network listener method for connectivity change.

Modified:

Create trip method should support creating trips without a user id.
Subscribe trip method should support the online trip.
Update trip method should be based on trip state.
Sync trip should have speed parameter.
Roam trip status should have trip state as parameter.
Unsubscribe trip method support for multiple trips.
Update time stamp field in trip listener.
Trip status code for control trip .

Fixed:

Offline trip reached_stop and left stop event are not getting called.
Drift issue fix.

0.1.2 - (Aug 02, 2022)

Added course field for offline trip

0.0.28 - (July 26, 2022)

Fixed:

Fixed location update gap in distance-based tracking.
Fixed stationary noise locations update when device gets stationary.

0.0.27 - (July 05, 2022)

Fixed:

Fixed Timestamp of offline trip events.

0.0.26 - (June 29, 2022)

Added:

Tracking configuration method for location accuracy improvement.

0.0.25 - (June 06, 2022)

Added:

Unsubscribe trip method for multiple trips ID.
Added timestamp field in the trip status listener.

0.1.1 - (May 30, 2022)

Fixed quick trip response.

0.0.24 - (May 24, 2022)

Fixed:

Location drift issue.
Receiver intent leaking issue

0.0.23 - (May 19, 2022)

Added:

Batch location update feature for trips.

Fixed:

Location listener and connectivity change listener issue.

0.0.22 - (May 14, 2022)

Added:

Network listener method for connectivity change.

0.0.21 - (April 29, 2022)

Added:

Batch location update feature.
Location count field for trips.

Modified:

Trip errors response.

0.0.20 - (April 21, 2022)

Fixed:

Fixed time-based tracking issue.

0.0.19 - (April 14, 2022)

Modified:

RoamPublish parameter as optional in updateCurrentLocation method.

0.0.18 - (April 6, 2022)

Fixed:

Removed noise locations update when the device gets idle during tracking.

0.1.0 - (Feb 25, 2022)

0.0.17 - (February 25, 2022)

Fixed:

Connection configuration for security and performance.

0.0.16 - (February 24, 2022)

Fixed:

Fixed stationary location update issue.

0.0.15 - (January 20, 2022)

Fixed:

Fixed logical error in the calculation of elevation gain in trips summary.

0.0.14 - (January 20, 2021)

Fixed:

Added option in Roam.unSubscribe() which will now unsubscribe all users if user_id is passed as null or empty.
Added battery and network details as part of location in location receiver. Fixed invalid location update data.

0.0.13 - (December 28, 2021)

Fixed:

Foreground notification method support for android 12.

0.0.12 - (December 10, 2021)

Fixed:

SDK installation support for Android 12.

0.0.11 - (November 26, 2021)

Modified:

Removed location permission status frequent updates.

Added:

Added "initialize validation" for each method.

0.0.10 - (November 16, 2021)

Modified:

Removed user-id validation for offline trips in the createTrip method.

0.0.9 - (November 8, 2021)

Added:

Added foreground service notification in SDK.
Added elevation gain support for offline trips.
Removed user-id validation for offline trips.

0.0.8 - (October 21, 2021)

Added:

Implemented location permission status.

0.0.7 - (October 7, 2021)

Added:

Support location subscription for cross-project within the same Account.

0.0.6 - (August 25, 2021)

Fixed:

Issue fixed on the location receiver method.

0.0.5 - (August 23, 2021)

Modified:

Make startTrip independent by combining it with startTracking and createTrip methods

Added:

metadata support for users and trips were added

0.0.4 - (August 6, 2021)

Modified:

Removed:

0.0.3 - (June 24, 2021)

Added:

Added the total elevation gain parameter to the already existing elevation gain, distance, and duration parameters in the trip summary.

0.0.2 - (June 18, 2021)

Fixed:

Fixed location receiver callbacks.

0.0.1 - (April 28, 2021)

The first version of Roam Android SDK

Changelog (iOS)

Keep yourself updated on any iOS changes.

0.1.19 - (Dec 05, 2023)

We're pleased to announce Roam iOS SDK version 0.1.19, primarily focused on resolving issues related to crashes occurring with Core Data and AWS IoT during location tracking in the background state and other rare scenarios. In this update, we've made the following fixes:

Core Data and AWS-IoT Crash Fixes: Addressed crashes occurring during location tracking in the background state and other infrequent scenarios related to Core Data and AWS IoT integrations. Users can now expect improved stability and reliability when utilizing these features.

These fixes aim to enhance the overall stability of the SDK, ensuring a smoother experience for developers and users alike. We're committed to providing a robust and dependable SDK. If you encounter any further issues or have feedback to share, please reach out to our support team. We're here to assist you promptly.

0.1.18 - (Nov 17, 2023)

We're excited to introduce Roam iOS SDK version 0.1.18, focusing on enhancing our network module and refining tracking logics. In this update, we've made the following improvements:

Enhanced Connectivity during Location Tracking: We've revamped the network module to handle few edge-cases on connectivity during location tracking. Expect smoother and more reliable communication between your app and Roam's services, ensuring a seamless experience for users even in challenging network conditions.
Minor Improvements to Tracking Logics: We've implemented minor refinements to our tracking logics. These subtle enhancements aim to fine-tune the tracking mechanisms, resulting in improved accuracy and efficiency when capturing and processing location data.

These improvements are geared towards providing a more robust and consistent experience for developers and users alike. We're dedicated to optimizing your tracking capabilities and ensuring a smoother operational experience. Should you have any inquiries or feedback, our support team is readily available to assist you.

0.1.17 - (Nov 02, 2023)

We're thrilled to present Roam iOS SDK version 0.1.17, focusing on bolstering our security module. In this update, we've made significant improvements to enhance the security of location data. Here's what's new:

Efficient Spoofed Location Detection: Our security algorithm has been refined to efficiently discard spoofed locations during the initial location fix. This enhancement ensures that only genuine and accurate location data is captured, enhancing the authenticity of the information gathered.
Addressing False Negatives: We've tackled false negatives during location tracking, ensuring that true locations are not mistakenly identified as spoofed locations. This refinement enhances the precision of location tracking, providing you with reliable and accurate data.

These security enhancements are designed to safeguard your data and ensure the integrity of the location information collected by the Roam iOS SDK. Your security is our priority, and we're committed to providing you with a secure and trustworthy experience. If you have any questions, concerns, or feedback, our support team is always here to assist you.

0.1.16 - (Oct 15, 2023)

We're excited to introduce Roam iOS SDK version 0.1.16, focusing on refining connectivity and enhancing tracking performance. In this update, we've made the following improvements:

Enhanced Connectivity: We've optimized the SDK's connectivity, ensuring smoother communication between your app and Roam's services. This enhancement leads to a more stable and reliable connection experience.
Improved Tracking Performance: Our team has worked diligently to enhance the overall tracking performance of the Roam iOS SDK. Expect better accuracy, responsiveness, and efficiency when tracking user data, providing a seamless experience for your users.

These improvements are designed to elevate your tracking capabilities and provide a more robust experience for both you and your users. As always, your feedback is invaluable to us. For any inquiries, support, or to share your feedback, don't hesitate to reach out to our dedicated support team. We're here to assist you every step of the way.

0.1.15 - (Sep 29, 2023)

We're thrilled to announce the release of Roam iOS SDK version 0.1.15, bringing powerful enhancements and simplified integration. Here's what's new:

Callback Integration: We've added callbacks to essential methods like startTracking, stopTracking, subscribe, unSubscribe, publishAndSave, and stopPublishing. These callbacks provide clear onSuccess and onError methods, ensuring you have complete control and real-time feedback for every SDK action.
Simplified Initialization: Now, initializing the Roam SDK is easier than ever. Simply place your publishable key in the .plist file, streamlining the setup process and getting you up and running swiftly.

Your feedback has been invaluable in shaping these improvements. For any queries, assistance, or to share your experiences, our support team is here to help.

0.1.14 - (Aug 29, 2023)

We're excited to announce the latest release of the Roam iOS SDK version 0.1.14. This update brings a significant enhancement that contributes to heightened security and user control. Read on to discover the key highlights of this release:

New Feature: Motion Detection Security With Roam iOS SDK v0.1.14, we introduce an innovative security feature—Motion Detection. This cutting-edge capability adds an extra layer of protection to your application's tracking experience. By enabling the verifyMotion parameter in the toggleSecurity() method, developers can now leverage motion patterns to enhance security. This empowers you to monitor and respond to unusual motion activities, ensuring a safer and more reliable tracking environment. As always, we appreciate your feedback and contributions in helping us refine and enhance the Roam iOS SDK. Please feel free to reach out to our support team if you have any questions, concerns, or suggestions. Stay tuned for more updates as we continue to improve the SDK's capabilities and features.

0.1.13 - (Aug 23, 2023)

We're excited to introduce Roam iOS SDK version 0.1.13, which includes a significant enhancement aimed at strengthening security within the SDK. Here's a breakdown of the latest changes:

New Security Module: Roam We've incorporated an advanced security module named Roam into the SDK. With this release, developers can take advantage of the toggleSecurity() method provided by Roam. This addition allows for seamless enabling and disabling of enhanced security measures. Protecting sensitive data is of paramount importance, and the Roam security module provides a streamlined way to fortify your application's defenses. As always, we appreciate your feedback and contributions in helping us refine and enhance the Roam iOS SDK. Please feel free to reach out to our support team if you have any questions, concerns, or suggestions. Stay tuned for more updates as we continue to improve the SDK's capabilities and features.

0.1.12 - (May 31, 2023)

Fixed the tracking issue during terminated state for SDK only tracking.

0.1.11 - (May 3, 2023)

Fixed multiple users creating when calling setDeviceToken method.

0.1.10 - (Mar 27, 2023)

Added few support for new error codes and messages in on didError delegate.

0.1.9 - (Mar 17, 2023)

Fixed a number of crashes that occurred while tracking in specific scenarios, improving the overall stability of the SDK.
Cleared console warnings to improve the developer experience.
Improved user subscription process for a smoother and more streamlined experience.
Improved location tracking logic to improve the accuracy and reliability of the SDK.
Overall performance and stability of the SDK have been improved.

0.1.8 - (Feb 24, 2023)

Activity recognition permission issues fixed.

0.1.7 - (Feb 13, 2023)

In this release, we have made the following improvements to enhance the user experience of our Roam iOS SDK:

Activity recognition methods: We have added activity recognition methods to the Roam iOS SDK to provide a more accurate and reliable determination of the user's current activity. This will improve the accuracy of location tracking, especially when the user is in motion.
Improved tracking logic: To further improve battery consumption, we have made some changes to our tracking logic. These changes are aimed at ensuring that the Roam SDK is as efficient as possible in terms of energy usage, while still providing accurate location tracking. We are confident that these changes will improve the overall experience of our Roam iOS SDK and we hope you enjoy these enhancements. If you have any questions or concerns, please feel free to reach out to us.

0.1.13 - (Aug 23, 2023)

We're excited to introduce Roam iOS SDK version 0.1.13, which includes a significant enhancement aimed at strengthening security within the SDK. Here's a breakdown of the latest changes:

New Security Module: Roam We've incorporated an advanced security module named Roam into the SDK. With this release, developers can take advantage of the toggleSecurity() method provided by Roam. This addition allows for seamless enabling and disabling of enhanced security measures. Protecting sensitive data is of paramount importance, and the Roam security module provides a streamlined way to fortify your application's defences.

As always, we appreciate your feedback and contributions in helping us refine and enhance the Roam iOS SDK. Please feel free to reach out to our support team if you have any questions, concerns, or suggestions. Stay tuned for more updates as we continue to improve the SDK's capabilities and features.

0.1.12 - (May 31, 2023)

Fixed the tracking issue during terminated state for SDK only tracking.

0.1.11 - (May 3, 2023)

Fixed mutiple users creating when calling setDeviceToken method.

0.1.10 - (Mar 27, 2023)

Added a few support for new error codes and messages on the didError delegate.

0.1.9 - (Mar 17, 2023)

Fixed a number of crashes that occurred while tracking in specific scenarios, improving the overall stability of the SDK.
Cleared console warnings to improve the developer experience.
Improved user subscription process for a smoother and more streamlined experience.
Improved location tracking logic to improve the accuracy and reliability of the SDK.
Overall performance and stability of the SDK have been improved.

0.1.8 - (Feb 24, 2023)

Activity recognition permission issue fixed.

0.1.7 - (Feb 13, 2023)

In this release, we have made the following improvements to enhance the user experience of our Roam iOS SDK:

Activity recognition methods: We have added activity recognition methods to the Roam iOS SDK to provide a more accurate and reliable determination of the user's current activity. This will improve the accuracy of location tracking, especially when the user is in motion.
Improved tracking logic: To further improve battery consumption, we have made some changes to our tracking logic. These changes are aimed at ensuring that the Roam SDK is as efficient as possible in terms of energy usage, while still providing accurate location tracking.

We are confident that these changes will improve the overall experience of our Roam iOS SDK and we hope you enjoy these enhancements. If you have any questions or concerns, please feel free to reach out to us.

0.1.6 - (Jan 20, 2023)

Tweaked the tracking algorithm for efficient battery consumption: We have made changes to our tracking algorithm to optimize battery consumption. The new algorithm is designed to reduce battery usage while maintaining the same level of accuracy and reliability.

0.1.5 - (Jan 20, 2023)

Added basic ingest publish topic for AWS cost optimization.
Fixed drift issue for distance-based tracking.

0.0.37 - (Jan 5, 2023)

Fixed drift issue for distance-based tracking.

0.1.4 - (Dec 25, 2022)

Fixed total elevation issue in sync trip.

0.1.3 - (Dec 16, 2022)

Added:

Added elevation gain parameter to trip listener.
Added speed parameter to location listener.

Fixed:

Location calibration when used along with accuracy config and time-based tracking.
Tracking config issue for time-based tracking.
Fixed crash when user received other user location.
Removed blue bar on user logout without stop tracking.
Fixed distance calculation logic for individual route points in RoamTripsSummary.

0.0.36 - (Nov 21, 2022)

Added a new Roam.requestAlwaysAuthorization() method for location permission control.

0.0.35 - (Nov 10, 2022)

Making SDK backwards compatible to support Xcode 13.X with Swift v5.6.1.

0.0.34 - (Nov 4, 2022)

Location calibration when used along with accuracy config and time-based tracking.
Added elevation gain parameter to trip listener.
Added speed parameter to location listener.

0.0.33 - (Oct 14, 2022)

Added support for Roam.initialize() with custom configurations.

0.0.32 - (Sept 29, 2022)

Made the SDK backwards compatible to support Xcode 14.x with Swift v5.7 along with the fix for crash issues while receiving other user locations.

0.0.31 - (Sept 28, 2022)

Made the SDK backwards compatible to support Xcode 13.x with Swift v5.6.1 along with the fix for the crash issues while receiving other user locations.

0.0.30 - (Sept 27, 2022)

Tracking config issue for time-based tracking.
Fixed crash when user received other user location.
Removed blue bar on user logout without stopping tracking.

0.1.2 - (August 25, 2022)

Added:

Added accuracy config methods for Roam.getCurrentLocation(), Roam.updateCurrentLocation() and Time based custom tracking.
Added timestamps to the trip listener data.
Added option to unsubscribe from all the trips in the method Roam.unsubscribeTripStatus()
Added new methods for batch configurations in trips data receiver.
Trips data in a trip receiver is changed from a single object to a list of updates.
Added new methods for batch configurations in location receiver.

Fixed:

Fixed crashing behavior while changing location permission.
Fixed blue bar issue for custom tracking modes.
Fixed location tracking issue when location permission is changed.
The fixed trip listener works independently of the location listener.
Fixes core data for location and trips.

0.1.1 - (May 12, 2022)

Fixed:

Crash when Roam.getTrip() is called without starting the trip.

Modified:

Removed user id validation for offline trips.
Create trip without user id. ie. optional
Support to update trip based on trip state.

Added:

Speed parameter to the routes in the trips summary.
Subscribe to online trips.

0.1.0 - (February 25, 2022)

Modified:

Updated new trip v2 methods. Refer Migration guide for more details.

0.0.29 - (August 30, 2022)

Fixed:

Fixed distance calculation logic for individual route points in RoamTripsSummary.

0.0.28 - (July 22, 2022)

Fixed:

Fixed crashing behavior while changing location permission.

0.0.27- (July 05, 2022)

Fixed:

Fixed build issues with v0.0.26.

0.0.26 - (July 04, 2022)

Added:

Added accuracy config methods for Roam.getCurrentLocation(), Roam.updateCurrentLocation() and Time based custom tracking.

Fixed:

Fixed blue bar issue for custom tracking modes.
Fixed location tracking issue when location permission is changed.

0.0.25 - (June 15, 2022)

Fixes:

Fix for #31 and #32

0.0.24 - (June 14, 2022)

Added:

Added timestamps to the trip listener data.
Created option to unsubscribe from all the trips in the method Roam.unsubscribeTripStatus().
The fixed trip listener works independently of the location listener.

0.0.23 - (May 25, 2022)

Added:

Added new methods for batch configurations in trips data receiver.
Trip data in a trip receiver is changed from a single object to a list of updates.

Fixed:

Fixes core data for location and trips.

0.0.22 - (May 6, 2022)

Added:

Added callbacks to Roam.resetBatchReceiverConfig method to return default config values.

0.0.21 - (April 29, 2022)

Added:

Added new methods for batch configurations in location receiver.
Updated trip error codes.

0.0.20 - (April 18, 2022)

Fixed:

Fixed calculation for distance and duration for individual location data in trip summary route.

0.0.19 - (April 14, 2022)

Added:

Added individual distance, duration, and elevation gain for location data inside trip routes for local trips.
Trip summary response for the local trip will have the route sorted by recorded timestamp.

Fixed:

Fixed background location tracking for time-based tracking mode when location permission is given as 'Allow while using'

0.0.18 - (April 1, 2022)

Fixed:

Fixed the coordinates arrangement for Roam.getTripSummary() on local trips.

0.0.17 - (February 7, 2022)

Fixed:

Removed the blue bar that was being displayed during active tracking.

0.0.16 - (January 19, 2022)

Modified:

Added an option in Roam.unSubscribe() which will now unsubscribe all users if user_id is passed as null or empty.
Added battery and network details as part of the location in the location receiver.

0.0.15 - (January 4, 2022)

Fixed:

Issues in tracking location when the application is forced to terminate by the user. The SDK will now restart the tracking automatically.

0.0.14 - (December 3, 2021)

Fixed:

Improved Roam.getCurrentLocation() to return the location faster.

0.0.13 - (November 15, 2021)

Fixed:

Location activity was getting updated as stationary for all location points during the terminated state.

0.0.12 - (November 15, 2021)

Modified:

Custom tracking options will now work in the terminated state. (SDK will wait for a significant change in the device location to restart the tracking again in the background)

0.0.11 - (October 20, 2021)

Added:

Support to listen to location updates of users from different projects which are in the same account.

Fixed:

Multiple location updates are recorded when the user is stationary while tracking.

0.0.10 - (August 20, 2021)

Modified:

#28 Made startTrip independent by combining it with startTracking and createTrip methods

Added:

metadata support for users and trips were added

0.0.9 - (August 2, 2021)

Modified:

#19 Allowed meta-data support for updating location, i.e., updateCurrentLocation method.

Removed:

#20 Combined startTracking and startSelfTracking methods.

Added:

#21 Updated location when a user becomes stationary.

0.0.8 - (July 23, 2021)

Fixed #23 - Tracking stops working after new getUser() or createUser() session

0.0.7 - (June 29, 2021)

#13 In order to support Apple Silicon M1 Macs, we added arm64 to iOS simulator builds.

0.0.6 - (June 29, 2021)

#5 Added support for XCFrameworks
#4 Added support for Swift Package Manager
#11 Updated the docs to support the SPM integration steps

0.0.5 - (June 25, 2021)

Updated dependency frameworks for XCFramworks to avoid build issues during manual integration.

0.0.4 - (June 24, 2021)

Refactored the current framework to support dependencies from local XCFrameworks.

0.0.3 - (June 24, 2021)

Added the total elevation gain parameter to the already existing elevation gain, distance, and duration parameters in the trip summary.
Added support new compiler version for Xcode 12.5.1 with Swift v5.4.2
Fix for #1 and #2

0.0.2 - (June 10, 2021)

Added:

isTripSync() Method

Fixed:

Fixed Location Id generation for Offline Trips

Modified:

Replaced AWSIOT with CocoaMQTT

0.0.1 - (April 12, 2021)

The first version of Roam iOS SDK

Trips

Explore Roam's Trips documentation.

Trips allow you to manage broadly defined trips. Whether it's a taxi driver, food/parcel delivery, outdoor run, or anyone who needs to move from location A to B, Roam.ai location technology helps manage the process.

Trips use a combination of REST APIs and SDK Methods for the creation and management of trips. Trips can be tracked in real-time using our SDK listener methods, webhooks, and our tracking portal track.roam.ai.

Quick Trips

Quick Trips lets you track journeys from point A to B in real-time using the startTrip and endTrip SDK methods.

Quick Trips are ideal for:

Fitness Tracking while on a run/ride.
Mileage tracking for employees, riders, etc.
Distance tracking for automobile rentals.
Micro mobility apps for short distance tracking.

Quick Trips Workflow

Planned Trips

Planned trips lets you plan trips ahead of time where a user can visit a single location or stop at multiple locations as part of the journey from point A to B to C to N. Start by creating a trip using createTrip including stop_locations where you can specify this location using coordinates of locations.

The best use cases for planned trips are:

Ridesharing and hailing
Food and Grocery delivery
Last-mile delivery
Logistics

Planned Trips Workflow

SDK Methods and APIs

Trips require you to use a combination of SDK Methods and APIs to achieve real-time tracking features.

Trip SDK Methods

Interaction with the Trip SDK Methods may require you to use user_id or trip_id while calling the methods.

Method Name

Description

Roam.createTrip

Allows you to create a Planned trip with stop_locations

Roam.updateTrip

Allows you to update a trip with user_id, stop_locations and more.

Roam.startTrip

Allows you to start a "Quick Trip" or a "Planned Trip" with pre-defined stop_locations.

Roam.endTrip

Allows you to end a Trip.

Roam.pauseTrip

Allows you to pause a Trip.

Roam.ResumeTrip

Allows you to resume a Trip.

Roam.syncTrip

Allows you to sync an offline Trip.

Roam.getTrip

Allows you to get the trip details using the trip_id.

Roam.getActiveTrips

Allows you to get a list of active trips for a specific user_id.

Roam.getTripSummary

Allows you to get a trip summary which includes the trip route, time taken, distance covered, and more.

Roam.subscribeTripStatus

Allows you to subscribe to the real-time status of any ongoing trip.

Roam.deleteTrip

Allows you delete any trip.

Trip APIs

The Roam API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

https://api.roam.ai/v2/trips

Authentication

The Roam API uses API keys to authenticate requests. You can view and manage your API keys in the Roam Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. Authentication to the API is performed via a custom header Api-Key. Provide your API key as the value for the header Api-Key

All API requests must be made over HTTPS. Calls made over plain HTTP and API requests without authentication will fail.

API Endpoint

Description

Create Trip

Allows you to create a Planned trip with or without origins and destinations.

Get Trip

Allows you to get the trip details using the trip_id.

Get Multiple Trips

Allows you to get multiple trips.

Update Trip

Allows you to update a trip with user_id, stop_locations and more.

Control Trips

Allows you to control a trip like start, end, pause and resume.

Trip Summary

Allows you to get a trip summary which includes the trip route, time taken, distance covered, and more.

Export Trip

Allows you to get a trip summary which includes the trip route, time taken, distance covered, and more.

Delete Trip

Allows you to delete any trip

API Objects

Trip Object

Attributes

Description

id

Unique identification of the trip object.

name

Name of the trip.

description

The trip's description.

metadata

A set of key-value pairs that you can attach to the trip object.

trip_state

The current state of the trip.

States: Created, Started, or Ended.

total_distance

Total distance covered by the user for this trip.

total_duration

Total duration taken by the user for this trip

toal_elevation_gain

Total positive elevation gain covered by the user for this trip.

started_at

Timestamp of when the trip started.

ended_at

Timestamp of when the trip ended.

created_at

Timestamp of when the trip was created.

updated_at

Timestamp of when the trip was last updated.

user

List of user objects.

events

List of event objects.

stops

List of stop objects.

User Object

Attributes

Description

id

Unique identification of the user object.

name

User name

description

User Description

metadata

A set of key-value pairs that you can attach to the user object.

Event Object

Attributes

Description

id

Unique identifier of the event Object

trip_id

ID associated with the trip.

user_id

User associated with the event.

event_type

Type of trip event: created, started, or ended.

created_at

Timestamp of when the event was created.

event_source

The source of this event, for example: "Trip"

event_version

Version of the event.

Stop Object

Attributes

Description

id

Unique identifier for the Stop Object

name

The name of the stop.

description

Stop description.

metadata

A Set of key-value pairs that you can attach to the user object.

geometry_radius

The geofence radius of the stop.

geometry

The coordinates of the stop geofence in geoJSON format.

arrived_at

Timestamp of when the user arrived/entered the stop.

departed_at

Timestamp of when the user departed/exited the stop.

created_at

Timestamp of when the stop was created.

updated_at

Timestamp of when the stop was updated.

The end-user can initiate different actions depending on the requirement. This is facilitated by the Roam SDK.

For example, when the end-user clicks on the Start Tracking icon on the frontend, the client-side requests to start tracking the user's location.

To use our Roam SDK on the server-side, the SDK object is instantiated using a private API key. The client request is made using the API which connects to the web server and retrieves the necessary data.

The following sections consist of code to instantiate the SDKs on the client side both on iOS and Android and the API requests corresponding to the actions.

Start Quick Trip

As the name suggests, a Quick Trip creates and starts the trip immediately. The user need not define the locations of travel and can track their journey from point A to point B using the startTrip and endTrip SDK methods on their application.

Refer to the following sections to instantiate the Start Quick Trip method on iOS and Android.

Update Trip

Update Trip allows you to update the name, description and the stop locations for a trip.

Consider a scenario where a trip is created with stop locations A, B, and C. If you wish to update the trip with a new stop location D, all the previously created stops need to be passed along with the co ordinates for point D.

If you wish to delete a stop location, you can do so by omitting the co ordinates for that point while updating the trip. However, you can only do so as long as the user has not reached that stop location.

Only stop locations that have not been reached yet can be deleted.

Refer to the following sections for the Update Trip API and SDK methods.

Create Trip

The Create Trip API, specifically used for planned trips, allows you to create new trips with start and stop locations. You can define the geometry radius for these locations which will help capture the entry and exit events.

To instantiate the Create Trip SDK, refer to the following section.

The following section consists of a sample request along with the responses for the Create Trip API.

Control Trip

Once the trip is created, the users can perform various actions to control it. The following sections consist of information on how to integrate the SDKs on iOS and Android devices and the APIs.

Start Trip

The Start Trip method allows you to start a Quick Trip or a planned trip with pre-defined stop locations.

To instantiate the Start Trip SDK method on Android and iOS, refer to the following sections.

The Start Trip API starts the trip for the specified Trip ID.

End Trip

The End Trip method is used to end an ongoing trip. The ended trip could be previously started, paused, and/or resumed.

Refer to the following section for information on how to instantiate the End Trip SDK on Android and iOS.

The End Trip API is used to end the trip for the given ID.

Pause Trip

The Pause Trip method allows the user to pause a previously created trip.

To instantiate the Pause Trip SDK on Android and iOS, refer to the following sections:

Pause Trip API pauses the trip for the given ID.

Resume Trip

The Resume Trip method is used to resume a previously paused trip.

The following section gives information on the Resume Trip SDK method for Android and iOS.

Resume trip API resumes the trip for the given Trip ID.

Sync Trip

The Sync Trip method syncs an offline trip (with locally stored data) to the servers.

The section below shows the code to instantiate the Sync Trip method on Android and iOS.

Get Trips

The Get Trips API fetches the trip details for the given Trip ID. The information will include the Trip ID, name, description, state, stop locations, entry and exit timestamps at the stop locations and so on.

Get Single Trip

As the name suggests, Get Single Trip is used to fetch details for a single Trip ID. Refer to the following sections to instantiate the Get Single Trip SDK method on iOS and Android.

Get Single Trip API fetches the trip details for the provided Trip ID.

Get Multiple Trips

Get Multiple Trips API will fetch multiple trip details. You can use different parameters to filter out the data to be fetched. For detailed information, refer to the section below.

Get Active Trips

A trip is active when it is started and not yet ended. The Get Active Trips method returns all the trips that have been started by the user.

Below are the Get Active Trips methods for Android and iOS.

Get Trip Summary

This method helps get the Trip Summary for the specified trip ID. To instantiate the Get Trip Summary method, refer the following section.

The Get Trip Summary API gives information about the entire trip with the start locations, end location stops, events, routes taken, etc.

Refer to the following section for detailed information about the API.

The Subscribe Trip method helps get real-time location data for trips. This method provides location data for both online and offline trips.

For more information on the Subscribe Trip method, refer to the following section.

To subscribe to trip events about end users, you configure Webhooks for your applications. A Webhook registers the notification URL that Roam sends notifications to.

To use the Developer Dashboard to subscribe to event notifications, refer to the following section.

There are several backend libraries you can subscribe to to receive user trips event data. We provide three libraries for location and events subscription.

For detailed information on how to integrate our JavaScript, Go and Python libraries, refer to the following sections.

Export Trip

The Export trip API call consolidates the trip summary in a readable format and exports the data to your system.

The different formats supported by Roam are csv, gpx, json and geojson. Refer to the following section for the API.

Delete Trip

The Delete Trip method deletes the trip regardless of its state.

To instantiate the Delete Trip method on Android and iOS, refer the following section.

The Delete Trip API makes a soft delete of the trip for the given trip ID.

Error Codes

The following are some of the commonly found codes indicating client errors.

Code

Message

Description

400

invalid_request_error

The request was unacceptable due to a missing parameter or an invalid parameter.

401

invalid_api_key

No valid API key provided or API key is missing.

402

account_error

The parameters were valid but the request failed due to either a payment error or the organization disabled it or you have exceeded your usage.

404

object_not_found

The requested object does not exist or has already been deleted.

429

rate_limit_exceeded

Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.

Live Tracking Link

Now that you know how to instantiate our SDK methods and how the APIs function, you can create, start and control the trips using the same. You can publish location updates and also subscribe to the trip using our Roam SDK. To receive real-time location updates, we have made a provision to subscribe to Webhooks and Backend libraries. However, you can also track the trip using our Roam Tracking Dashboard.

The Roam Tracking dashboard is a fully responsive, platform compatible, and an easy-to-use interface that helps track the end-user location during a trip.

You can either provide the UserID or the TripID to start tracking. You can also create a new user with an existing API Key.

The Tracking dashboard shows the following:

The number of stops in the created trip.
The total distance traveled from the start to the end location.
The duration taken to travel the distance.
The arrival and departure timestamps for the entry and exit events at each stop location.
ID of the end-user who traversed the distance.

In the above example, we have created a trip with three stop locations. Once the trip is created and started, the stop locations are visible on the tracking dashboard in yellow.

Check out the video below for a short demo of the tracking dashboard.

Once the trip is ended, you can see the start point indicated in green, stop locations in yellow, and the endpoint in red.

Geofencing

Explore Roam's Geofencing documentation.

Geofence is a virtual perimeter for a real-world geographical area. A geofence can be dynamically generated around a location point with a radius (circle geofence) or with a pre-defined set of boundaries (polygon geofence) for stores, neighborhoods, or even cities.

Every time the end user enters or exits a geofence with a location aware device, events are generated. These events can be used to alert the user or perform actions in the backend.

Base URL

https://api.roam.ai/v1/api/geofence

Authentication

Roam API uses API keys to authenticate requests. You can view and manage your API keys in the Roam Dashboard.

All API requests must be made over HTTPS. Calls made over plain HTTP and API requests without authentication will fail.

Create Geofence

Geofences can be created using the Roam API. They can be created over a circle or a polygon geometry. By default, a geofence is applicable to all the users of a project but can also be restricted to a group of users. Geofences can be configured to be enabled for a specified time interval.

Geofence Types:

Roam allows you to create two geofence geometry types:

Circle
Polygon

Circle Geofence

A circular geofence is the region around a location point defined by a radius. To create a circular geofence, the required body parameters are coordinates, and geometry_radius .

Sample Request // Circle Geofence

curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
--header 'Content-Type: application/json' \
--data-raw '{
	"coordinates": [ -72.28122, 42.926042 ] ,
	"geometry_radius": 177,
	"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"]
}'

Sample Response // Circle Geofence

RESPONSE 200:OK

{
    "status": true,
    "msg": "Geofence Added successfully.",
    "code": 201,
    "data": {
        "geofence_id": "60e59c73ffb3fb58a9c6eb64",
        "geometry_type": "circle",
        "geometry_radius": 177,
        "geometry_center": {
            "type": "Point",
            "coordinates": [
                -72.28122,
                42.926042
            ]
        },
        "is_enabled": [
            true,
            "2021-06-10T18:45:00.000",
            "2021-06-10T19:29:00.000"
        ],
        "is_deleted": false,
        "created_at": "2021-07-07T12:22:11.105",
        "updated_at": "2021-07-07T12:22:11.105"
    }
}

Polygon Geofence

A polygon geofence is the area defined by a set of boundaries forming any shape around a location area. To create a polygon geofence, the required body parameters are geometry_type andcoordinates.

Same Request to create a Polygon geofence

curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
--header 'Content-Type: application/json' \
--data-raw '
{
   "coordinates":[
      [
         -0.08789347686767579,
         51.50619618452938
      ],
      [
         -0.0905934768676758,
         51.50619618452938
      ],
      [
         -0.0905934768676758,
         51.503796184529385
      ],
      [
         -0.08789347686767579,
         51.50619618452938
      ]
   ],
   "is_enabled": [
      true,
      "2021-06-10T18:45:00",
      "2021-06-10T19:29:00"
    ]
}'

Sample Response

{
    "status": true,
    "msg": "Geofence Added successfully.",
    "code": 201,
    "data": {
        "geofence_id": "60e59cfaffb3fb58a8c6eb66",
        "geometry": {
            "type": "Polygon",
            "coordinates": [
                [
                    [
                        -0.08789347686767579,
                        51.50619618452938
                    ],
                    [
                        -0.0905934768676758,
                        51.50619618452938
                    ],
                    [
                        -0.0905934768676758,
                        51.503796184529385
                    ],
                    [
                        -0.08789347686767579,
                        51.50619618452938
                    ]
                ]
            ]
        },
        "geometry_type": "polygon",
        "geometry_center": {
            "type": "Point",
            "coordinates": [
                -0.08969347686882724,
                51.505396185373506
            ]
        },
        "is_enabled": [
            true,
            "2021-06-10T18:45:00.000",
            "2021-06-10T19:29:00.000"
        ],
        "is_deleted": false,
        "created_at": "2021-07-07T12:24:26.197",
        "updated_at": "2021-07-07T12:24:26.197"
    }
}

User Specific Geofence

You can monitor geofence events for a specific user or a list of users by passing user_ids which are generated at the time of creating a user. In the case of a user group, you may pass the group_id. If by default, user_ids and group_ids are not specified, then the geofence is activated for all the users of the project.

Based on the User ID

Pass a user_id under the "user_ids" body parameter. Pass an array ofuser_idsto create a geofence specific to multiple users.

Sample Request for single User ID

curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
--header 'Content-Type: application/json' \
--data-raw '{
	"geometry_type": "circle",
	"coordinates": [ -72.28122, 42.926042 ] ,
	"geometry_radius": 177,
	"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"],
	"user_ids": ["6bda16edea01848b3b419163"]
}'

Sample Request for multiple User IDs

curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
--header 'Content-Type: application/json' \
--data-raw '{
	"geometry_type": "circle",
	"coordinates": [ -72.28122, 42.926042 ] ,
	"geometry_radius": 177,
	"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"],
	"user_ids": ["6bda16edea01848b3b419163", "6bda16edea01848b3b419163"]
}'

Based on Group ID

Pass a group_id under the "group_ids" body parameter. You may pass multiple group IDs into an array to create a geofence specific to those groups.

Sample Request for single Group ID

curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
--header 'Content-Type: application/json' \
--data-raw '{
	"geometry_type": "circle",
	"coordinates": [ -72.28122, 42.926042 ] ,
	"geometry_radius": 177,
	"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"],
	"group_ids": ["6bda16edea01848b3b419163"]
}'

Sample Request for multiple Group ID

curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
--header 'Content-Type: application/json' \
--data-raw '{
	"geometry_type": "circle",
	"coordinates": [ -72.28122, 42.926042 ] ,
	"geometry_radius": 177,
	"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"],
	"group_ids": ["6bda16edea01848b3b419163", "6bda16edea01848b3b419163"]
}'

Time-Aware Geofence

You can create time aware geofences to trigger events between a specific time range. You can do so by passing the date and time as the second and third elements of the array to theis_enabledfield in the body section.

During the specified time interval, the entry and exit events will be triggered. However, outside the time interval, you need to ensure that the"is_enabled" field is set to "false".

curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
--header 'Content-Type: application/json' \
--data-raw '{
	"geometry_type": "circle",
	"coordinates": [ -72.28122, 42.926042 ] ,
	"geometry_radius": 177,
	"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"]
}'

Sample Response

{
    "status": true,
    "msg": "Geofence Added successfully.",
    "code": 201,
    "data": {
        "geofence_id": "60e59e9effb3fb58a3c6eb69",
        "geometry_type": "circle",
        "geometry_radius": 177,
        "geometry_center": {
            "type": "Point",
            "coordinates": [
                -72.28122,
                42.926042
            ]
        },
        "is_enabled": [
            true,
            "2021-06-10T18:45:00.000",
            "2021-06-10T19:29:00.000"
        ],
        "is_deleted": false,
        "created_at": "2021-07-07T12:31:26.437",
        "updated_at": "2021-07-07T12:31:26.437"
    }
}

Personalize Geofence

Description and Metadata

Adding a description and metadata can help identify and personalize the geofences while displaying them on a map. You can add this information while creating a geofence or updating a geofence.

Sample Request

curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
--header 'Content-Type: application/json' \
--data-raw '{
	"geometry_type": "circle",
	"coordinates": [ -72.28122, 42.926042 ] ,
	"geometry_radius": 177,
	"description": "Google New York City",
  "metadata": {
  							"object_id": "10000234243241234",
  							"google_user_id": "000034"
  },
	"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"]
}'

Sample Response

{
  "status": true,
  "msg": "Geofence Added successfully.",
  "code": 201,
  "data": {
    "geofence_id": "60ee5decffb3fb728a120cb4",
    "geometry_type": "circle",
    "geometry_radius": 177,
    "geometry_center": {
      "type": "Point",
      "coordinates": [
        -72.28122,
        42.926042
      ]
    },
    "is_enabled": [
      true,
      "2021-06-10T18:45:00.000",
      "2021-06-10T19:29:00.000"
    ],
    "description": "Google New York City",
    "metadata": {
      "object_id": "10000234243241234",
      "google_user_id": "000034"
    },
    "is_deleted": false,
    "created_at": "2021-07-14T03:45:48.842",
    "updated_at": "2021-07-14T03:45:48.842"
  }
}

Tags and Color Codes

Adding tag can help filter geofences easily. This field is optional. When a geofence event is generated, the tag is also sent along with the event.

color_code defines the color of the geofence and how it is displayed on the dashboard. Hex Code for CSS colors should be passed in this field without '#'.

Sample Request

curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
--header 'Content-Type: application/json' \
--data-raw '{
	"coordinates": [ -72.28122, 42.926042 ] ,
	"geometry_radius": 177,
	"description": "Google New York City",
	"metadata": {
        "object_id": "10000234243241234",
        "google_user_id": "000034"
        },
  "tag": "home",
  "color_code": "ffffff",
	"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"]
}'

Sample Response

{
  "status": true,
  "msg": "Geofence Added successfully.",
  "code": 201,
  "data": {
    "geofence_id": "60ee5e1effb3fb728c120d88",
    "geometry_type": "circle",
    "geometry_radius": 177,
    "geometry_center": {
      "type": "Point",
      "coordinates": [
        -72.28122,
        42.926042
      ]
    },
    "is_enabled": [
      true,
      "2021-06-10T18:45:00.000",
      "2021-06-10T19:29:00.000"
    ],
    "description": "Google New York City",
    "color_code": "ffffff",
    "tag": "home",
    "metadata": {
      "object_id": "10000234243241234",
      "google_user_id": "000034"
    },
    "is_deleted": false,
    "created_at": "2021-07-14T03:46:38.674",
    "updated_at": "2021-07-14T03:46:38.674"
  }
}

Update Geofence

Geofence can be updated using PUT API request along with the geofence endpoint.

The following are the values that can be updated once after the Geofence is created.

Parameters

Type

group_ids

array

user_ids

array

metadata

object

color_code

string

tag

string

description

string

is_enabled

array

The values that cannot be updated once the geofence is created are:

Parameters

Type

coordinates

array

geometry_type

string

geometry_radius

integer

Get Geofence

This API gives you a filtered list of geofences. You can filter by geofence_id, created_at, start_date and end_date fields, user_id and group_id.

Sample Request

Using start_date and end_date

This filter allows you to filter the geofences within the given date range. These are non-mandatory fields and will be set to the current date by default.

You may also pass either the start_date or the end_date as filters. If you pass a specific start date, make sure it is less than the current date since the end date will be set default to the current date. If you pass a specific end_date and leave the start_date empty, make sure it is greater than the current date.

Below are the acceptable formats for the date filter:

Parameter

Mandatory

Format

Default

start_date

YYYY-MM-DD

Current date

end_date

YYYY-MM-DD

Current date

curl --location --request GET 'https://api.roam.ai/v1/api/geofence/?start_date=2020-09-28&end_date=2020-09-29' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88'

Using geofence_id

You can also use geofence_id as a filter. If you pass a valid geofence_id, the results will be filtered to the given geofence id.

You can get the geofence_id when you create a geofence using the Create Geofence API.

If you use a geofence_id as a filter along with a date filter, the date filters will not be considered.

Passing an empty or invalid geofence_id, will return an error.

Make sure the geofence_id used here belongs to the same project linked to the API key.

curl --location --request GET 'https://api.roam.ai/v1/api/geofence/?geofence_id=5f73326ce5fc231ba4b253eb' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88'

Using user_id

Similar to the geofence_id, you can fetch the list of geofences that are tagged with the given user_id, which was initially used during the Create Geofence API. The user_id is created within the SDK during thecreateUser method and returns a unique user_id for identification within the Roam environment.

If you use theuser_id as a filter along with the date filter, the date filters will not be considered. And if you pass an empty or invalid user_id, the API will return an error.

Make sure the user_id used here belongs to the same project linked with the API key.

curl --location --request GET 'https://api.roam.ai/v1/api/geofence/?user_id=6073325bcf3e4eba5a1123a' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88'

Using group_id

To fetch the list of geofences that are tagged with the given group_id, which was initially used during the Create Geofence API, you can pass the group_id in the header parameter.

You can get the group_id when you create a group using the Create Group API.

If you use group_id as a filter along with the date filter, the date filters will not be considered. Passing an empty or invalid group_id, will return an error.

Make sure the group_id used here belongs to the same project linked with the API key.

curl --location --request GET 'https://api.roam.ai/v1/api/geofence/?group_id=6073325bc3fe343ab6c1324b' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88'

Geofence Events

Roam's geofence feature has 2 possible events that can be triggered based on user behavior:

Geofence Entry Event - triggered when a user enters the defined geofence area
Geofence Exit Event - triggered when a user exits from the defined geofence area

Sample Events:

Geofence Entry Event:

{
    "events": [
        {
            "user_id": "60e5646151efb06fe4c65b0d",
            "location_id": "60e566a4fa8a780000ed3194",
            "geofence_id": "60e566a28ce7db5726c1c1cd",
            "recorded_at": "2021-07-07T08:32:36.243Z",
            "event_source": "geospark:geofence",
            "event_version": "1.0",
            "event_type": "geospark:geofence:entry",
            "location": {
                "type": "Point",
                "coordinates": [
                    77.5573154,
                    9.4551286
                ]
            },
            "speed": 0,
            "course": 316.1922912597656,
            "altitude": 78.46394327410016,
            "activity": "M",
            "vertical_accuracy": null,
            "horizontal_accuracy": 10.565999984741211
        }
    ]
}

Geofence Exit Event:

{
    "events": [
        {
            "user_id": "60e5646151efb06fe4c65b0d",
            "location_id": "60e566a4fa8a780000ed3194",
            "geofence_id": "60e566a28ce7db5726c1c1cd",
            "recorded_at": "2021-07-07T08:32:36.243Z",
            "event_source": "geospark:geofence",
            "event_version": "1.0",
            "event_type": "geospark:geofence:exit",
            "location": {
                "type": "Point",
                "coordinates": [
                    77.5573154,
                    9.4551286
                ]
            },
            "speed": 0,
            "course": 316.1922912597656,
            "altitude": 78.46394327410016,
            "activity": "M",
            "vertical_accuracy": 5,
            "horizontal_accuracy": 10.565999984741211
        }
    ]
}

Enable Events

To enable geofence events for a user, you’ll need to ensure the following:

Under Roam.toggleEvents the geofence flag must be set to true ,and
Ensure you’re publishing location to the server.

Toggle Events docs Links: iOS | Android | React Native | Using API

Publish Locations docs links: iOS | Android | React Native

If the geofence flag is false for a user and location is not being published, then geofence events will not be processed for their location updates.

Events via Webhook

Roam supports the posting of events to webhooks in real-time. To enable posting events via webhook, first the webhook URL needs to be configured in the project using the dashboard (Project Settings -> integration) and should be enabled.

Events via API

Geofence events can be retrieved using the Roam API. The Get Events API lets you fetch entry or exit events of the users from your event-enabled geofences. The API also lets you filter by user, geofence, location, and more.

Delete Geofence

Delete any existing geofences from your projects by using the geofence_id.

You can delete the geofence with the delete API using the following two options:

Option 1: Delete geofence individually

You can delete one geofence at a time by passing the geofence ID as a query parameter.

Option 2: Delete geofences in bulk

By passing multiple geofence_ids as a body parameter, you can delete up to 200 geofences at a time.

Error Codes

Method

Status

Message

Reason

GET

400

"Error": [ "start_date provided is greater than end_date." ]

Invalid date filter

GET

400

"geofence_id": { "geofence_id": "This field is invalid." }

Invalid geofence id

GET

400

"Error": [ "Geofence does not exist." ]

Geofence does not exist

GET

400

"Error": [ "You are not authorized." ]

Invalid API key

GET

400

"Error": [ "Maximum 7 days data is allowed at a time." ]

Date filter greater than the limit of 7 days

GET

400

"ErrorMessage": "An error occurred"

Unknown server error

POST

400

"coordinates": [ "Invalid coordinates for given geometry type" ]

Invalid geofence geometry coordinates

POST

400

"enable_at": [ "DateTime has wrong format. Provide as YYYY-MM-DDThh:mm:ss" ]

Invalid date time format

POST

400

"non_field_errors": [ "enable_at provided is greater than disable_at." ]

Invalid enable_at value

POST

400

"non_field_errors": [ "disable_at field is required when enable_at field is present." ]

Empty disable_at value

POST

400

"non_field_errors": [ "enable_at field is required when disable_at field is present." ]

Empty enable_at value

POST

400

"Invalid is_enabled format. Allowed format: [bool, enable_at, disable_at]"

Invalid is_enabled format

POST

400

"coordinates": [ "Coordinates must be sent in a list" ]

Invalid coordinates

POST

400

"geometry_radius": [ "This field is required." ]

Empty geometry radius

POST

400

"tag": { "tag": "This field is invalid." }

Invalid tag

PUT

400

"geofence_id": { "geofence_id": "This field is invalid." }

Invalid geofence id

DELETE

400

"details": "This geofence is part of an active campaign."

Geofence cannot be deleted since it is part of an active campaign

DELETE

400

"geofence_id": { "geofence_id": "This field is invalid." }

Invalid geofence id

{
   "code": 200,
   "description": "The trip summary for requested id.",
   "message": "trip_summary",
   "trip": {
       "id": "6221bf4393ade81ce90c8c5c",
       "trip_state": "ended",
       "total_distance": 1942.08,
       "total_duration": 328,
       "total_elevation_gain": 52,
       "name": "trip name",
       "description": "trip description",
       "metadata": {
           "Key1": "value1"
       },
       "start_location": {
           "id": "6221bf683d4d460000e33446",
           "metadata": {},
           "address": "Bailey Road, Priyadarshi Nagar, Danapur, Dinapur-Cum-Khagaul, Patna District, Bihar, 801506, India",
           "recorded_at": "2022-03-04T07:27:36.645",
           "geometry": {
               "type": "Point",
               "coordinates": [
                   85.06961939,
                   25.60647234
               ]
           }
       },
       "end_location": {
           "id": "6221c1493d4d460000e334c1",
           "metadata": {},
           "address": "Priyadarshi Nagar, Danapur, Dinapur-Cum-Khagaul, Patna District, Bihar, 800018, India",
           "recorded_at": "2022-03-04T07:35:37.382",
           "geometry": {
               "type": "Point",
               "coordinates": [
                   85.06689824,
                   25.61904625
               ]
           }
       },
       "started_at": "2022-03-04T07:27:36.645",
       "ended_at": "2022-03-04T07:35:37.382",
       "created_at": "2022-03-04T07:26:59.480",
       "updated_at": "2022-03-04T07:35:39.913",
       "user": {
           "id": "6221bc24ffb3fb125a2e2342",
           "name": "",
           "description": "",
           "metadata": {
               "Mobile": "1234567890",
               "Name": "Nikhil"
           }
       },
       "stops": [
           {
               "id": "6221bf4393ade81ce90c8c5b",
               "name": "STOP 1",
               "description": "tea break",
               "metadata": {
                   "Key1": "value1"
               },
               "address": "Bangalore",
               "geometry_radius": 600,
               "geometry": {
                   "type": "Point",
                   "coordinates": [
                       85.30614739,
                       23.5155215
                   ]
               },
               "created_at": "2022-03-04T07:26:59.475",
               "updated_at": "2022-03-04T07:26:59.475",
               "arrived_at": null,
               "departed_at": null
           }
       ],
       "events": [
           {
               "id": "6221bf45b5ef8c40ac13ff5e",
               "trip_id": "6221bf4393ade81ce90c8c5c",
               "location_id": "",
               "user_id": "6221bc24ffb3fb125a2e2342",
               "event_type": "roam:trip:created",
               "created_at": "2022-03-04T07:27:01.615",
               "event_source": "roam:trip",
               "event_version": "1.0"
           },
           {
               "id": "6221bf6e1674e3543f398a40",
               "trip_id": "6221bf4393ade81ce90c8c5c",
               "location_id": "6221bf683d4d460000e33446",
               "user_id": "6221bc24ffb3fb125a2e2342",
               "event_type": "roam:trip:started",
               "created_at": "2022-03-04T07:27:41.257",
               "event_source": "roam:trip",
               "event_version": "1.0"
           },
           {
               "id": "6221c0701674e3543f398a41",
               "trip_id": "6221bf4393ade81ce90c8c5c",
               "location_id": "6221c06d3d4d460000e3346c",
               "user_id": "6221bc24ffb3fb125a2e2342",
               "event_type": "roam:trip:paused",
               "created_at": "2022-03-04T07:31:59.919",
               "event_source": "roam:trip",
               "event_version": "1.0"
           },
           {
               "id": "6221c0e1b5ef8c40ac13ff5f",
               "trip_id": "6221bf4393ade81ce90c8c5c",
               "location_id": "6221c0dd3d4d460000e33492",
               "user_id": "6221bc24ffb3fb125a2e2342",
               "event_type": "roam:trip:resumed",
               "created_at": "2022-03-04T07:33:53.222",
               "event_source": "roam:trip",
               "event_version": "1.0"
           },
           {
               "id": "6221c14d1674e3543f398a42",
               "trip_id": "6221bf4393ade81ce90c8c5c",
               "location_id": "6221c1493d4d460000e334c1",
               "user_id": "6221bc24ffb3fb125a2e2342",
               "event_type": "roam:trip:ended",
               "created_at": "2022-03-04T07:35:41.291",
               "event_source": "roam:trip",
               "event_version": "1.0"
           }
       ],
       "route_indexes": [
           [
               1,
               39
           ],
           [
               40,
               86
           ]
       ],
       "route": [
           {
               "coordinates": {
                   "coordinates": [
                       85.06961939,
                       25.60647234
                   ],
                   "type": "Point"
               },
               "speed": 0,
               "altitude": 110,
               "activity": "STOP",
               "recorded_at": "2022-03-04T07:27:36.645",
               "metadata": null,
               "distance": 0,
               "duration": 0,
               "elevation_gain": 0
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06968719,
                       25.60665091
                   ],
                   "type": "Point"
               },
               "speed": 13,
               "altitude": 129.82,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:28:31.744",
               "metadata": null,
               "distance": 21.01,
               "duration": 55,
               "elevation_gain": 19
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06948914,
                       25.60671479
                   ],
                   "type": "Point"
               },
               "speed": 6,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:28:41.816",
               "metadata": null,
               "distance": 42.12,
               "duration": 65,
               "elevation_gain": 20
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06929126,
                       25.60677863
                   ],
                   "type": "Point"
               },
               "speed": 14,
               "altitude": 129.38,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:29:04.882",
               "metadata": null,
               "distance": 63.21,
               "duration": 88,
               "elevation_gain": 20
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06904013,
                       25.60685963
                   ],
                   "type": "Point"
               },
               "speed": 24,
               "altitude": 129.91,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:29:09.838",
               "metadata": null,
               "distance": 89.98,
               "duration": 92,
               "elevation_gain": 20
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06883539,
                       25.60692568
                   ],
                   "type": "Point"
               },
               "speed": 7,
               "altitude": 129.44,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:29:16.823",
               "metadata": null,
               "distance": 111.8,
               "duration": 98,
               "elevation_gain": 20
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06863859,
                       25.60698916
                   ],
                   "type": "Point"
               },
               "speed": 12,
               "altitude": 129.26,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:29:30.928",
               "metadata": null,
               "distance": 132.78,
               "duration": 112,
               "elevation_gain": 20
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.0684211,
                       25.60706062
                   ],
                   "type": "Point"
               },
               "speed": 22,
               "altitude": 128.27,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:29:35.939",
               "metadata": null,
               "distance": 156.01,
               "duration": 117,
               "elevation_gain": 20
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06820577,
                       25.60713976
                   ],
                   "type": "Point"
               },
               "speed": 16,
               "altitude": 127.77,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:29:41.011",
               "metadata": null,
               "distance": 179.35,
               "duration": 122,
               "elevation_gain": 20
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06800858,
                       25.60721223
                   ],
                   "type": "Point"
               },
               "speed": 11,
               "altitude": 127.61,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:29:45.849",
               "metadata": null,
               "distance": 200.72,
               "duration": 126,
               "elevation_gain": 20
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06781342,
                       25.60728395
                   ],
                   "type": "Point"
               },
               "speed": 9,
               "altitude": 128.85,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:10.860",
               "metadata": null,
               "distance": 221.87,
               "duration": 151,
               "elevation_gain": 21
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06759802,
                       25.60736312
                   ],
                   "type": "Point"
               },
               "speed": 18,
               "altitude": 128.68,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:15.998",
               "metadata": null,
               "distance": 245.21,
               "duration": 156,
               "elevation_gain": 21
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06739371,
                       25.60743821
                   ],
                   "type": "Point"
               },
               "speed": 11,
               "altitude": 129.95,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:21.892",
               "metadata": null,
               "distance": 267.35,
               "duration": 161,
               "elevation_gain": 23
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.0672014,
                       25.60751067
                   ],
                   "type": "Point"
               },
               "speed": 12,
               "altitude": 128.69,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:26.826",
               "metadata": null,
               "distance": 288.27,
               "duration": 165,
               "elevation_gain": 23
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06700945,
                       25.60758558
                   ],
                   "type": "Point"
               },
               "speed": 16,
               "altitude": 128.34,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:32.845",
               "metadata": null,
               "distance": 309.26,
               "duration": 171,
               "elevation_gain": 23
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06679251,
                       25.60767003
                   ],
                   "type": "Point"
               },
               "speed": 17,
               "altitude": 128.24,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:38.918",
               "metadata": null,
               "distance": 332.97,
               "duration": 177,
               "elevation_gain": 23
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06660112,
                       25.60774419
                   ],
                   "type": "Point"
               },
               "speed": 13,
               "altitude": 128.32,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:42.852",
               "metadata": null,
               "distance": 353.88,
               "duration": 180,
               "elevation_gain": 23
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06638153,
                       25.60782928
                   ],
                   "type": "Point"
               },
               "speed": 19,
               "altitude": 127.84,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:47.844",
               "metadata": null,
               "distance": 377.87,
               "duration": 184,
               "elevation_gain": 23
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.0661767,
                       25.60790865
                   ],
                   "type": "Point"
               },
               "speed": 26,
               "altitude": 128.25,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:52.856",
               "metadata": null,
               "distance": 400.24,
               "duration": 189,
               "elevation_gain": 23
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06594634,
                       25.60799497
                   ],
                   "type": "Point"
               },
               "speed": 31,
               "altitude": 128.76,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:55.981",
               "metadata": null,
               "distance": 425.28,
               "duration": 192,
               "elevation_gain": 24
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06573304,
                       25.60807386
                   ],
                   "type": "Point"
               },
               "speed": 31,
               "altitude": 127.26,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:58.857",
               "metadata": null,
               "distance": 448.42,
               "duration": 194,
               "elevation_gain": 24
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06547511,
                       25.60817058
                   ],
                   "type": "Point"
               },
               "speed": 34,
               "altitude": 128.9,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:01.830",
               "metadata": null,
               "distance": 476.46,
               "duration": 196,
               "elevation_gain": 25
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06521008,
                       25.60824988
                   ],
                   "type": "Point"
               },
               "speed": 31,
               "altitude": 129.79,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:04.882",
               "metadata": null,
               "distance": 504.49,
               "duration": 199,
               "elevation_gain": 26
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.0649913,
                       25.6083136
                   ],
                   "type": "Point"
               },
               "speed": 25,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:07.885",
               "metadata": null,
               "distance": 527.56,
               "duration": 202,
               "elevation_gain": 26
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06477762,
                       25.60837584
                   ],
                   "type": "Point"
               },
               "speed": 29,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:11.031",
               "metadata": null,
               "distance": 550.1,
               "duration": 205,
               "elevation_gain": 26
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06452776,
                       25.60844861
                   ],
                   "type": "Point"
               },
               "speed": 32,
               "altitude": 129.09,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:13.865",
               "metadata": null,
               "distance": 576.45,
               "duration": 207,
               "elevation_gain": 26
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06426739,
                       25.60851561
                   ],
                   "type": "Point"
               },
               "speed": 31,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:16.873",
               "metadata": null,
               "distance": 603.63,
               "duration": 210,
               "elevation_gain": 27
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06405443,
                       25.60857429
                   ],
                   "type": "Point"
               },
               "speed": 24,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:19.974",
               "metadata": null,
               "distance": 625.98,
               "duration": 213,
               "elevation_gain": 27
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06386509,
                       25.60864441
                   ],
                   "type": "Point"
               },
               "speed": 24,
               "altitude": 129.01,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:22.914",
               "metadata": null,
               "distance": 646.52,
               "duration": 215,
               "elevation_gain": 27
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06364274,
                       25.60872913
                   ],
                   "type": "Point"
               },
               "speed": 31,
               "altitude": 128.36,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:26.044",
               "metadata": null,
               "distance": 670.75,
               "duration": 218,
               "elevation_gain": 27
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06341159,
                       25.60881739
                   ],
                   "type": "Point"
               },
               "speed": 20,
               "altitude": 129.18,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:29.963",
               "metadata": null,
               "distance": 695.94,
               "duration": 221,
               "elevation_gain": 28
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06322453,
                       25.60888629
                   ],
                   "type": "Point"
               },
               "speed": 23,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:33.856",
               "metadata": null,
               "distance": 716.22,
               "duration": 224,
               "elevation_gain": 29
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06302312,
                       25.60895644
                   ],
                   "type": "Point"
               },
               "speed": 19,
               "altitude": 129.83,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:38.029",
               "metadata": null,
               "distance": 737.89,
               "duration": 228,
               "elevation_gain": 29
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06280411,
                       25.60903273
                   ],
                   "type": "Point"
               },
               "speed": 22,
               "altitude": 128.76,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:41.848",
               "metadata": null,
               "distance": 761.45,
               "duration": 231,
               "elevation_gain": 29
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06256706,
                       25.60911529
                   ],
                   "type": "Point"
               },
               "speed": 22,
               "altitude": 128.39,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:45.793",
               "metadata": null,
               "distance": 786.95,
               "duration": 234,
               "elevation_gain": 29
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.0623316,
                       25.6091994
                   ],
                   "type": "Point"
               },
               "speed": 31,
               "altitude": 129.52,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:48.884",
               "metadata": null,
               "distance": 812.37,
               "duration": 237,
               "elevation_gain": 30
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06211789,
                       25.60929494
                   ],
                   "type": "Point"
               },
               "speed": 27,
               "altitude": 128.6,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:51.924",
               "metadata": null,
               "distance": 836.31,
               "duration": 240,
               "elevation_gain": 30
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06193204,
                       25.60937814
                   ],
                   "type": "Point"
               },
               "speed": 24,
               "altitude": 129.52,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:54.941",
               "metadata": null,
               "distance": 857.13,
               "duration": 243,
               "elevation_gain": 31
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06182,
                       25.60942829
                   ],
                   "type": "Point"
               },
               "speed": 0,
               "altitude": 129.91,
               "activity": "STOP",
               "recorded_at": "2022-03-04T07:31:57.273",
               "metadata": null,
               "distance": 869.68,
               "duration": 245,
               "elevation_gain": 31
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06280688,
                       25.61014692
                   ],
                   "type": "Point"
               },
               "speed": 0,
               "altitude": 127.47762887,
               "activity": "STOP",
               "recorded_at": "2022-03-04T07:33:51.349",
               "metadata": null,
               "distance": 869.68,
               "duration": 0,
               "elevation_gain": 31
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06297614,
                       25.61050536
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 129.96,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:33:53.057",
               "metadata": null,
               "distance": 913.04,
               "duration": 246,
               "elevation_gain": 34
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06306297,
                       25.61068923
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:33:55.087",
               "metadata": null,
               "distance": 935.28,
               "duration": 248,
               "elevation_gain": 34
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.0631498,
                       25.6108731
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:33:56.975",
               "metadata": null,
               "distance": 957.52,
               "duration": 249,
               "elevation_gain": 34
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06323663,
                       25.61105697
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 129.62,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:33:58.909",
               "metadata": null,
               "distance": 979.76,
               "duration": 250,
               "elevation_gain": 34
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06331741,
                       25.61122804
                   ],
                   "type": "Point"
               },
               "speed": 34,
               "altitude": 129.15,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:01.095",
               "metadata": null,
               "distance": 1000.45,
               "duration": 252,
               "elevation_gain": 34
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06339631,
                       25.61139512
                   ],
                   "type": "Point"
               },
               "speed": 38,
               "altitude": 127.42,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:02.978",
               "metadata": null,
               "distance": 1020.66,
               "duration": 253,
               "elevation_gain": 34
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06348155,
                       25.61157489
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 125.79,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:04.978",
               "metadata": null,
               "distance": 1042.42,
               "duration": 255,
               "elevation_gain": 34
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06356958,
                       25.6117583
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 126.78,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:07.109",
               "metadata": null,
               "distance": 1064.66,
               "duration": 257,
               "elevation_gain": 35
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06365239,
                       25.61194366
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 127.96,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:09.097",
               "metadata": null,
               "distance": 1086.9,
               "duration": 258,
               "elevation_gain": 36
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06372888,
                       25.61211659
                   ],
                   "type": "Point"
               },
               "speed": 34,
               "altitude": 128.9,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:11.004",
               "metadata": null,
               "distance": 1107.62,
               "duration": 259,
               "elevation_gain": 37
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06380536,
                       25.61228952
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:13.006",
               "metadata": null,
               "distance": 1128.34,
               "duration": 261,
               "elevation_gain": 38
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06390366,
                       25.61246859
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:14.985",
               "metadata": null,
               "distance": 1150.58,
               "duration": 262,
               "elevation_gain": 38
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06397223,
                       25.61264941
                   ],
                   "type": "Point"
               },
               "speed": 36,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:16.988",
               "metadata": null,
               "distance": 1171.85,
               "duration": 264,
               "elevation_gain": 38
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06403591,
                       25.61282275
                   ],
                   "type": "Point"
               },
               "speed": 36,
               "altitude": 128.43,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:18.946",
               "metadata": null,
               "distance": 1192.17,
               "duration": 265,
               "elevation_gain": 38
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.0641024,
                       25.6129951
                   ],
                   "type": "Point"
               },
               "speed": 36,
               "altitude": 127.34,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:21.022",
               "metadata": null,
               "distance": 1212.48,
               "duration": 267,
               "elevation_gain": 38
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06418866,
                       25.61316979
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 127.88,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:22.997",
               "metadata": null,
               "distance": 1233.76,
               "duration": 268,
               "elevation_gain": 39
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06430193,
                       25.61339917
                   ],
                   "type": "Point"
               },
               "speed": 30,
               "altitude": 128.38,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:26.011",
               "metadata": null,
               "distance": 1261.71,
               "duration": 271,
               "elevation_gain": 39
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06441341,
                       25.61362491
                   ],
                   "type": "Point"
               },
               "speed": 38,
               "altitude": 129.56,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:29.227",
               "metadata": null,
               "distance": 1289.21,
               "duration": 274,
               "elevation_gain": 40
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06452199,
                       25.6138474
                   ],
                   "type": "Point"
               },
               "speed": 29,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:32.071",
               "metadata": null,
               "distance": 1316.26,
               "duration": 276,
               "elevation_gain": 41
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06460088,
                       25.61401364
                   ],
                   "type": "Point"
               },
               "speed": 36,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:34.039",
               "metadata": null,
               "distance": 1336.38,
               "duration": 277,
               "elevation_gain": 41
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06468287,
                       25.6141864
                   ],
                   "type": "Point"
               },
               "speed": 37,
               "altitude": 129.06,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:35.987",
               "metadata": null,
               "distance": 1357.29,
               "duration": 278,
               "elevation_gain": 41
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06477006,
                       25.61437013
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 128.43,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:38.046",
               "metadata": null,
               "distance": 1379.53,
               "duration": 280,
               "elevation_gain": 41
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06485726,
                       25.61455386
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 128.77,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:40.104",
               "metadata": null,
               "distance": 1401.77,
               "duration": 282,
               "elevation_gain": 41
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06494445,
                       25.6147376
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:42.115",
               "metadata": null,
               "distance": 1424.01,
               "duration": 284,
               "elevation_gain": 42
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06503091,
                       25.61491977
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 128.43,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:44.000",
               "metadata": null,
               "distance": 1446.06,
               "duration": 285,
               "elevation_gain": 42
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06511283,
                       25.61510362
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 129.57,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:46.054",
               "metadata": null,
               "distance": 1468.11,
               "duration": 287,
               "elevation_gain": 43
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06519253,
                       25.61528579
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 128.22,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:48.054",
               "metadata": null,
               "distance": 1489.9,
               "duration": 289,
               "elevation_gain": 43
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06527387,
                       25.6154717
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 127.24,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:50.034",
               "metadata": null,
               "distance": 1512.14,
               "duration": 290,
               "elevation_gain": 43
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.0653552,
                       25.6156576
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 128.53,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:52.010",
               "metadata": null,
               "distance": 1534.38,
               "duration": 291,
               "elevation_gain": 45
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06546331,
                       25.6159047
                   ],
                   "type": "Point"
               },
               "speed": 35,
               "altitude": 127.5,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:55.108",
               "metadata": null,
               "distance": 1563.95,
               "duration": 294,
               "elevation_gain": 45
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06557565,
                       25.61615026
                   ],
                   "type": "Point"
               },
               "speed": 35,
               "altitude": 126.02,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:58.035",
               "metadata": null,
               "distance": 1593.51,
               "duration": 296,
               "elevation_gain": 45
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06566061,
                       25.61633543
                   ],
                   "type": "Point"
               },
               "speed": 29,
               "altitude": 126.06,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:01.010",
               "metadata": null,
               "distance": 1615.81,
               "duration": 298,
               "elevation_gain": 45
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06574934,
                       25.61652881
                   ],
                   "type": "Point"
               },
               "speed": 27,
               "altitude": 124.9,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:04.062",
               "metadata": null,
               "distance": 1639.1,
               "duration": 301,
               "elevation_gain": 45
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06583606,
                       25.61671781
                   ],
                   "type": "Point"
               },
               "speed": 27,
               "altitude": 125.89,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:07.030",
               "metadata": null,
               "distance": 1661.86,
               "duration": 303,
               "elevation_gain": 46
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06592368,
                       25.61690647
                   ],
                   "type": "Point"
               },
               "speed": 27,
               "altitude": 125.79,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:10.019",
               "metadata": null,
               "distance": 1684.62,
               "duration": 305,
               "elevation_gain": 46
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06601764,
                       25.61710781
                   ],
                   "type": "Point"
               },
               "speed": 32,
               "altitude": 127.84,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:13.039",
               "metadata": null,
               "distance": 1708.93,
               "duration": 308,
               "elevation_gain": 48
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06613094,
                       25.61735059
                   ],
                   "type": "Point"
               },
               "speed": 36,
               "altitude": 127.83,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:16.005",
               "metadata": null,
               "distance": 1738.25,
               "duration": 310,
               "elevation_gain": 48
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06624213,
                       25.61759282
                   ],
                   "type": "Point"
               },
               "speed": 36,
               "altitude": 125.88,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:19.022",
               "metadata": null,
               "distance": 1767.43,
               "duration": 313,
               "elevation_gain": 48
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06631701,
                       25.61776256
                   ],
                   "type": "Point"
               },
               "speed": 36,
               "altitude": 126.07,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:21.013",
               "metadata": null,
               "distance": 1787.76,
               "duration": 314,
               "elevation_gain": 48
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06639542,
                       25.61794028
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 127.75,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:23.027",
               "metadata": null,
               "distance": 1809.05,
               "duration": 316,
               "elevation_gain": 50
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06647734,
                       25.61812598
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 127.96,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:25.079",
               "metadata": null,
               "distance": 1831.29,
               "duration": 318,
               "elevation_gain": 50
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06655628,
                       25.61830491
                   ],
                   "type": "Point"
               },
               "speed": 37,
               "altitude": 128.07,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:27.089",
               "metadata": null,
               "distance": 1852.72,
               "duration": 320,
               "elevation_gain": 50
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06666323,
                       25.61854686
                   ],
                   "type": "Point"
               },
               "speed": 33,
               "altitude": 126.67,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:30.067",
               "metadata": null,
               "distance": 1881.71,
               "duration": 322,
               "elevation_gain": 50
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06677069,
                       25.61877522
                   ],
                   "type": "Point"
               },
               "speed": 33,
               "altitude": 124.07,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:33.186",
               "metadata": null,
               "distance": 1909.32,
               "duration": 325,
               "elevation_gain": 50
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06686524,
                       25.61897614
                   ],
                   "type": "Point"
               },
               "speed": 27,
               "altitude": 125.17,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:36.054",
               "metadata": null,
               "distance": 1933.61,
               "duration": 327,
               "elevation_gain": 51
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06689824,
                       25.61904625
                   ],
                   "type": "Point"
               },
               "speed": 0,
               "altitude": 126.05,
               "activity": "STOP",
               "recorded_at": "2022-03-04T07:35:37.382",
               "metadata": null,
               "distance": 1942.08,
               "duration": 328,
               "elevation_gain": 52
           }
       ],
       "is_local": false
   }
}

Roam v1

Introduction

SDKs

APIs

Getting Started

1. Create a Roam Account

2. Try our example app

3. Start integrating

4. Get support

Key Concepts

Location update

Location module

Location Tracker

Location Publisher

Location Listener

Location Processor

Location tracking mode

Frameworks

Android

Quickstart (Android)

Requirements

Run the example application

Android Studio Setup

SDK Installation

Gradle Installation

Manual Installation

Initialize the SDK

Request Permission

Location Tracking

Start Tracking

Tracking Modes

Adaptive Tracking

Distance Interval Tracking

Time Interval Tracking

Stop Tracking

Location Listeners

Batch Configuration

Set Batch Configuration

Get Batch Configuration

Reset Batch Configuration

Pub/Sub Locations (Android)

Creating Users

Get User

Location Tracking

Start Tracking

Tracking Modes

Custom Tracking Modes

Stop Tracking

Publish Locations

Subscribe to Messages

Subscribe

UnSubscribe

Location Listener

Toggle Events

Location Listener

SDK Methods (Android)

SDK Configuration (Android)

Set Tracking in AppState

Offline Location Tracking

Allow Mock Location

Accuracy Engine

Set Foreground Service Notification

Get Current Location (Android)

Current Location

Update Current Location (Android)

Update Location When Stationary (Android)

Trip v1 SDK Methods (Android)

Create Trip

Get Trip Details

Start and Stop Trip

Start Trip

Stop Trip

Pause and Resume Trip

Pause Trip

Resume Trip

Subscribe to Trip Status

Get Trip Status

Get Active Trips

Get Trip Summary

Trip v2 SDK Methods (Android)