Roam.ai Docs
HomeContactDashboard
  • Introduction
  • Getting Started
    • Key Concepts
  • Frameworks
  • Android
    • Quickstart (Android)
    • Pub/Sub Locations (Android)
    • SDK Methods (Android)
      • SDK Configuration (Android)
      • Get Current Location (Android)
      • Update Current Location (Android)
      • Update Location When Stationary (Android)
      • Trip v1 SDK Methods (Android)
      • Trip v2 SDK Methods (Android)
        • Create Trip (Android)
        • Update Trip (Android)
        • Start Quick Trip (Android)
        • Start Trip (Android)
        • End Trip (Android)
        • Pause Trip (Android)
        • Resume Trip (Android)
        • Sync Trip (Android)
        • Get Trip (Android)
        • Get Active Trips (Android)
        • Get Trip Summary (Android)
        • Subscribe to Trip (Android)
        • Delete Trip (Android)
    • Utility Methods (Android)
    • Troubleshooting (Android)
    • Changelog (Android)
  • iOS
    • Quickstart (iOS)
    • Pub/Sub Locations (iOS)
    • SDK Methods (iOS)
      • SDK Configuration (iOS)
      • Get Current Location (iOS)
      • Update Current Location (iOS)
      • Update Location When Stationary (iOS)
      • Trips v1 SDK Methods (iOS)
      • Trips v2 SDK Methods (iOS)
        • Create Trip (iOS)
        • Update Trip (iOS)
        • Start Quick Trip (iOS)
        • Start Trip (iOS)
        • End Trip (iOS)
        • Pause Trip (iOS)
        • Resume Trip (iOS)
        • Sync Trip (iOS)
        • Get Trip (iOS)
        • Get Active Trips (iOS)
        • Get Trip Summary (iOS)
        • Subscribe Trip (iOS)
        • Delete Trip (iOS)
    • Utility Methods (iOS)
    • Troubleshooting (iOS)
    • Changelog (iOS)
  • React Native
  • Flutter
  • PRODUCTS
  • Tracking (BETA)
  • Geofencing
  • Trips
  • APIs
    • Authorization
    • Users API
      • Create User API
      • Get User API
      • Update User API
    • Locations API
      • Get Locations API
      • Get Stop Locations API
    • Insights API
      • Get User POIs API
      • Get User Home Location API
      • Get User Work Location API
    • Trips v1 API
      • Create Trip API v1
      • Get Trip API
      • Update Trip API v1
      • Delete Trip API v1
      • Trip Summary API
      • Export Trip Summary as GPX
    • Trips v2 API
      • Create Trip API
      • Get Single Trip API
      • Get Multiple Trips API
      • Update Trip API
      • Control Trip API
        • Start Trip API
        • Pause Trip API
        • Resume Trip API
        • End Trip API
      • Get Trip Summary API
      • Export Trip API
      • Delete Trip API
    • Geofencing API
      • CREATE Geofence API
      • GET Geofence API
      • UPDATE Geofence API
      • DELETE Geofence API
    • Events API
      • Get Events
      • Trip Events
    • Nearby API
      • Get Nearby User API
      • Get Nearby Geofence API
    • Moving Geofence API
      • Create Moving-Geofence API
      • Update Moving-Geofence API
      • GET Moving-Geofence API
      • Delete Moving-Geofence API
    • User Groups API
      • Create Group API
      • Get User Group by ID
      • Get User Group List
      • Add Users to Group API
      • Update Group API
      • Find Nearby Users from Group
    • Query with Metadata
  • WEBHOOK
    • Webhook
    • Slack Integration
  • LIBRARIES
    • Javascript Library
    • Go Library
    • Python Library
Powered by GitBook
On this page
  • Creating Users
  • Location Tracking
  • Publish Locations
  • Subscribe to Messages
  • Location Listener
  • Toggle Events
  • Location Listener

Was this helpful?

Export as PDF
  1. Android

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.

// create user with meta-data and description
// Declare meta-data as json
// Description as string
val metadata = JSONObject() 
metadata.put("key", "value") 
Roam.createUser("SET-USER-DESCRIPTION-HERE", metadata, 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 the error code & message below
        // roamError.getCode()
        // roamError.getMessage()
      }
})
// update user with meta-data and description
// Declare meta-data as dictionary
// Description as string
JSONObject metadata = new JSONObject(); 
metadata.put("key", "value"); 
Roam.createUser("YOUR-USER-DESCRIPTION-GOES-HERE", metadata, 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();
            }
        });

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.

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

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

Type

Unit

Unit Range

Distance Interval

Meters

1m ~ 2500m

Time Interval

Seconds

10s ~ 10800s

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

Subscribe to Messages

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.

Subscribe

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

Type

Description

Roam.Subscribe.EVENTS

Subscribe to your own events.

Roam.Subscribe.LOCATION

Subscribe to your own location (or) other user's location updates.

Roam.Subscribe.BOTH

Subscribe to your own events and location (or) other user's location updates.

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.

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
    }
}
PreviousQuickstart (Android)NextSDK Methods (Android)

Last updated 1 year ago

Was this helpful?

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 for continuous tracking.

foreground service