SDKs

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

Requirements

To use the Roam SDK,

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

1. Go to Android Studio > New Project > Minimum SDK

2. Select API 16: Android 4.1.0 (Jelly Bean) or higher and create a project

3. After you create a new project, open Gradle Scripts > build.gradle (Project: <your_project>) and do the following:

   1. Add the following to the build script {repositories {}} section of the build.gradle (Project)file:

      Copy

      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

1. Open Android Studio and add the SDK Roam.aar as a module using File > New > New Module > Import .JAR/.AAR Package.

2. Once Gradle is finished, click File > Project Structure again.

3. Click on the Dependencies tab > click App > click the “+” icon in the top left of the Declared Dependencies section > select Module Dependency > click on Roam-release > press Ok and wait for Gradle to sync again.

4. Make sure to include the dependencies separately and sync your project.

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:

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

2. Configure Your Manifest File:

   • In your Manifest file, declare your Roam publish key as follows:

   Copy

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

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

   Copy

   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)

   Copy

   defaultConfig {
           Properties properties = new Properties()
           properties.load(project.rootProject.file('local.properties').newDataInputStream())
           manifestPlaceholders = [ROAM_PUBLISH_KEY: "${properties.getProperty('ROAM_PUBLISH_KEY')}"]
   
       }

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

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

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.

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.

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

1. The NetworkState.BOTH indicates the state in which the updates are to be received. It can either be set to online, offline, or both.

2. The batchCount indicates the size of the location batch.

3. The batchWindow indicates the time interval for every consecutive update (frequency of updates).

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.

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

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

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

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.

1. Callback Method which returns the current location with a faster response time. However, the accuracy depends on the current GPS connectivity.

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

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.

Add the code to the receiver.

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

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.

Get Trip Details

Start and Stop Trip

Start Trip

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

Stop Trip

Pause and Resume Trip

Pause Trip

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

Resume Trip

To resume the trip,

Subscribe to Trip Status

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

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

Get Trip Status

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.

Get Trip Summary

A Quick Trip creates and starts a trip immediately with a single method. Creating a quick trip is similar to creating a 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:

To access trip responses:

To access user details:

To access error details:

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.

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.

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:

To access the trip response:

To access user details:

To access stop details:

To access error details:

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

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

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

 Roam.pauseTrip("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.

Set Tracking in AppState

Roam.setTrackingInAppState(STATE)

Roam.setTrackingInAppState(STATE);

Offline Location Tracking

Roam.offlineLocationTracking(Boolean)

Roam.offlineLocationTracking(Boolean);

Allow Mock Location

Roam SDKs reject Mock Locations on the device by default.

Roam.allowMockLocation(Boolean)

Roam.allowMockLocation(Boolean);

Accuracy Engine

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

Roam.enableAccuracyEngine()

Roam.enableAccuracyEngine();

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

Roam.enableAccuracyEngine("DESIRED-ACCURACY-VALUE")

Roam.enableAccuracyEngine("DESIRED-ACCURACY-VALUE");

For disabling accuracy engine

 Roam.disableAccuracyEngine()

 Roam.disableAccuracyEngine();

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.

// ENABLE as Boolean (mandatory)
// TITLE as String (mandatory)
// DESCRIPTION as String (mandatory)
// ICON as String (mandatory)
// ACTIVITY_PATH as String (mandatory)
// FOREGROUND_SERVICE_PATH as String (mandatory)

Roam.setForegroundNotification(ENABLE,"TITLE","DESCRIPTION","ICON",
"ACTIVITY_PATH","FOREGROUND_SERVICE_PATH")

// ENABLE as Boolean (mandatory)
// TITLE as String (mandatory)
// DESCRIPTION as String (mandatory)
// ICON as String (mandatory)
// ACTIVITY_PATH as String (mandatory)
// FOREGROUND_SERVICE_PATH as String (mandatory)

Roam.setForegroundNotification(ENABLE,"TITLE","DESCRIPTION","ICON",
"ACTIVITY_PATH","FOREGROUND_SERVICE_PATH");

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

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

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.

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.

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.

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:

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.

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

RoamTrackingMode roamTrackingMode = new RoamTrackingMode.Builder(distanceFilter, stopDuration)
                        .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
                        .build();
                        
Roam.getTrip("tripId", new RoamTripCallback() {
                    @Override
                    public void onSuccess(RoamTripResponse response) {
                       //get trip details
                    }

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

 Roam.getTrip("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.

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.

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

Requirements

To use the Roam SDK, the following things are 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

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.

1. Go to Xcode > File > New Project

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

   Copy

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

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

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

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:

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

2. Configure Your .plist File:

   • In your info.plist file, declare your Roam publish key as follows:

   Copy

   <key>ROAM_PUBLISH_KEY</key>
   <string>$(ROAM_PUBLISH_KEY)</string>

   • Replace "$(ROAM_PUBLISH_KEY)" with your actual Roam publish key.

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

   Copy

   ROAM_PUBLISH_KEY = XXXXXXXXXXXXXX

4. Initialization Code:

   • Initialize Roam SDK in your application as follows:

   Copy

   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.

1. Import CoreLocation at the top of the AppDelegate file.

   Copy

   import CoreLocation

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

   Copy

   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.

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

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

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.

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.

1. The networkState indicates the state in which the updates are to be received. It can either be set to online, offline, or both.

2. The batchCount indicates the size of the location batch.

3. The batchWindow indicates the time interval for every consecutive update (frequency of updates).

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

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.

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
}];