Pub/Sub Locations

Creating Users

Once the SDK is initialized, we need to create or get a user to start the tracking and use other methods. Every user created will have a unique Cyprinus identifier which will be used later to login and access developer APIs. We can call it as Cyprinus userId.
Kotlin
Java
1
Roam.createUser("SET-USER-DESCRIPTION-HERE", object : RoamCallback {
2
override fun onSuccess(roamUser: RoamUser) {
3
// Access Roam user data below
4
// roamUser.getUserId();
5
// roamUser.getDescription();
6
// roamUser.getEventListenerStatus();
7
// roamUser.getLocationListenerStatus();
8
// roamUser.getLocationEvents();
9
// roamUser.getGeofenceEvents();
10
// roamUser.getMovingGeofenceEvents();
11
// roamUser.getTripsEvents();
12
}
13
14
override fun onFailure(roamError: RoamError) {
15
// Access error code & message below
16
// roamError.getCode()
17
// roamError.getMessage()
18
}
19
})
Copied!
1
Roam.createUser("YOUR-USER-DESCRIPTION-GOES-HERE", new RoamCallback() {
2
@Override
3
public void onSuccess(RoamUser roamUser) {
4
// Access Roam user data below
5
// roamUser.getUserId();
6
// roamUser.getDescription();
7
// roamUser.getEventListenerStatus();
8
// roamUser.getLocationListenerStatus();
9
// roamUser.getLocationEvents();
10
// roamUser.getGeofenceEvents();
11
// roamUser.getMovingGeofenceEvents();
12
// roamUser.getTripsEvents();
13
}
14
15
@Override
16
public void onFailure(RoamError roamError) {
17
// Access error code & message below
18
// roamError.getCode();
19
// roamError.getMessage();
20
}
21
});
Copied!
The option user description 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 later using the below code.
Kotlin
Java
1
Roam.setDescription("SET-USER-DESCRIPTION-HERE")
Copied!
1
Roam.setDescription("SET-USER-DESCRIPTION-HERE");
Copied!

Get User

If you already have a Cyprinus userID which you would like to reuse instead of creating a new user, use the below to get user session.
Kotlin
Java
1
Roam.getUser("ROAM-USER-ID", object : RoamCallback {
2
override fun onSuccess(roamUser: RoamUser) {
3
// Access Roam user data below
4
// roamUser.getUserId();
5
// roamUser.getDescription();
6
// roamUser.getEventListenerStatus();
7
// roamUser.getLocationListenerStatus();
8
// roamUser.getLocationEvents();
9
// roamUser.getGeofenceEvents();
10
// roamUser.getMovingGeofenceEvents();
11
// roamUser.getTripsEvents();
12
}
13
14
override fun onFailure(roamError: RoamError) {
15
// Access error code & message below
16
// roamError.getCode()
17
// roamError.getMessage()
18
}
19
})
Copied!
1
Roam.getUser("YOUR-ROAM-USER-ID", new RoamCallback() {
2
@Override
3
public void onSuccess(RoamUser roamUser) {
4
// Access Roam user data below
5
// roamUser.getUserId();
6
// roamUser.getDescription();
7
// roamUser.getEventListenerStatus();
8
// roamUser.getLocationListenerStatus();
9
// roamUser.getLocationEvents();
10
// roamUser.getGeofenceEvents();
11
// roamUser.getMovingGeofenceEvents();
12
// roamUser.getTripsEvents();
13
}
14
15
@Override
16
public void onFailure(RoamError roamError) {
17
// Access error code & message below
18
// roamError.getCode();
19
// roamError.getMessage();
20
}
21
});
Copied!

Location Tracking

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

Start Tracking

Kotlin
Java
1
Roam.startTracking(TrackingMode)
Copied!
1
Roam.startTracking(TrackingMode);
Copied!
Use the tracking modes while you use the startTracking method Roam.startTracking

Tracking Modes

Cyprinus has three default tracking modes along with a custom version. They differ based on the frequency of location updates and battery consumption. The higher the frequency, the higher is the battery consumption. You must use foreground service for continuous tracking.
Mode
Battery usage
Updates every
Optimised for/advised for
Active
6% - 12%
25 ~ 250 meters
Ride Hailing / Sharing
Balanced
3% - 6%
50 ~ 500 meters
On Demand Services
Passive
0% - 1%
100 ~ 1000 meters
Social Apps
Kotlin
Java
1
// active tracking
2
Roam.startTracking(RoamTrackingMode.ACTIVE)
3
// balanced tracking
4
Roam.startTracking(RoamTrackingMode.BALANCED)
5
// passive tracking
6
Roam.startTracking(RoamTrackingMode.PASSIVE)
Copied!
1
// active tracking
2
Roam.startTracking(RoamTrackingMode.ACTIVE);
3
// balanced tracking
4
Roam.startTracking(RoamTrackingMode.BALANCED);
5
// passive tracking
6
Roam.startTracking(RoamTrackingMode.PASSIVE);
Copied!

Custom Tracking Modes

The 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:
Kotlin
Java
1
// Define a custom tracking method with desired distance interval, stop duration and accuracy
2
val trackingMode = RoamTrackingMode.Builder(<DISTANCE-FILTER-IN-METERS>, <STOP-INTERVAL-IN-SECONDS>)
3
.setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
4
.build()
5
// Start the tracking with the above created custom tracking method
6
Roam.startTracking(trackingMode);
Copied!
1
// Define a custom tracking method with desired distance interval, stop duration and accuracy
2
RoamTrackingMode trackingMode = new RoamTrackingMode.Builder(<DISTANCE-FILTER-IN-METERS>, <STOP-INTERVAL-IN-SECONDS>)
3
.setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
4
.build();
5
// Start the tracking with the above created custom tracking method
6
Roam.startTracking(trackingMode);
Copied!
Time between location updates example code:
Kotlin
Java
1
// Define a custom tracking method with desired time interval and accuracy
2
val trackingMode = RoamTrackingMode.Builder(<TIME-INTERVAL-IN-SECONDS>)
3
.setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
4
.build()
5
// Start the tracking with the above created custom tracking method
6
Roam.startTracking(trackingMode)
Copied!
1
// Define a custom tracking method with desired time interval and accuracy
2
RoamTrackingMode trackingMode = new RoamTrackingMode.Builder(<TIME-INTERVAL-IN-SECONDS>)
3
.setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
4
.build();
5
// Start the tracking with the above created custom tracking method
6
Roam.startTracking(trackingMode);
Copied!
You may see a delay if the user's device is in low power mode or has connectivity issues.

Stop Tracking

To stop the tracking use the below method.
Kotlin
Java
1
Roam.stopTracking()
Copied!
1
Roam.stopTracking();
Copied!

Publish Locations

It will publish location data and these data will be sent to Cyprinus servers for further processing and data will be saved in our database servers.
Kotlin
Java
1
val locationData = RoamPublish.Builder().build()
2
Roam.publishAndSave(locationData)
Copied!
1
RoamPublish locationData = new RoamPublish.Builder().build();
2
Roam.publishAndSave(locationData);
Copied!
To stop publishing locations.
Kotlin
Java
1
Roam.stopPublishing()
Copied!
1
Roam.stopPublishing();
Copied!

Subscribe 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

Kotlin
Java
1
Roam.subscribe(TYPE, "ROAM-USER-ID");
Copied!
1
GeoSpark.subscribe(TYPE, "USER-ID");
Copied!

UnSubscribe

Kotlin
Java
1
Roam.unSubscribe(TYPE, "ROAM-USER-ID")
Copied!
1
Roam.unSubscribe(TYPE, "ROAM-USER-ID");
Copied!
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.

Location Listener

Before adding listerners 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 set to false and needs to be set to true in order to stream the location and events updates to the same device or other devices.
Kotlin
Java
1
Roam.toggleListener(locations, events, object : RoamCallback {
2
override fun onSuccess(roamUser: RoamUser) {
3
// do something when toggle listener success
4
// access locations listener status with roamUser.getLocationListenerStatus()
5
// access events listener status with roamUser.getEventListenerStatus()
6
}
7
8
override fun onFailure(roamError: RoamError) {
9
// do something when toggle listener failure
10
}
11
})
Copied!
1
Roam.toggleListener(true, true, new RoamCallback() {
2
@Override
3
public void onSuccess(RoamUser roamUser) {
4
// Access Roam user data below
5
// roamUser.getUserId();
6
// roamUser.getDescription();
7
// roamUser.getEventListenerStatus();
8
// roamUser.getLocationListenerStatus();
9
// roamUser.getLocationEvents();
10
// roamUser.getGeofenceEvents();
11
// roamUser.getMovingGeofenceEvents();
12
// roamUser.getTripsEvents();
13
}
14
15
@Override
16
public void onFailure(RoamError roamError) {
17
// Access error code & message below
18
// roamError.getCode();
19
// roamError.getMessage();
20
}
21
});
Copied!
You can also get the current status of listeners with the below method.
Kotlin
Java
1
Roam.getListenerStatus(object : RoamCallback {
2
override fun onSuccess(roamUser: RoamUser) {
3
// do something when get listener status success
4
// get location listener status with roamUser.getLocationListenerStatus
5
// get events listener status with roamUser.getEventListenerStatus
6
}
7
override fun onFailure(roamError: RoamError) {
8
// do something when get listener status failure
9
}
10
})
Copied!
1
Roam.getListenerStatus(new RoamCallback() {
2
@Override
3
public void onSuccess(RoamUser roamUser) {
4
// Access Roam user data below
5
// roamUser.getUserId();
6
// roamUser.getDescription();
7
// roamUser.getEventListenerStatus();
8
// roamUser.getLocationListenerStatus();
9
// roamUser.getLocationEvents();
10
// roamUser.getGeofenceEvents();
11
// roamUser.getMovingGeofenceEvents();
12
// roamUser.getTripsEvents();
13
}
14
15
@Override
16
public void onFailure(RoamError roamError) {
17
// Access error code & message below
18
// roamError.getCode();
19
// roamError.getMessage();
20
}
21
});
Copied!
To listen to events on the server-side, you should enable events for the user using the method below.
Kotlin
Java
1
Roam.toggleEvents(geofence, trip, location, movingGeofence, object : RoamCallback {
2
override fun onSuccess(roamUser: RoamUser) {
3
// do something when toggle events success
4
// access location events status with roamUser.getLocationEvents()
5
// access geofence events status with roamUser.getGeofenceEvents()
6
// access trips events status with roamUser.getTripsEvents()
7
// get moving geofence event status with roamUser.getMovingGeofenceEvents()
8
}
9
10
override fun onFailure(error: roamError) {
11
// do something when toggle events failure
12
}
Copied!
1
Roam.toggleEvents(true, true, true, true, new RoamCallback() {
2
@Override
3
public void onSuccess(RoamUser roamUser) {
4
// Access Roam user data below
5
// roamUser.getUserId();
6
// roamUser.getDescription();
7
// roamUser.getEventListenerStatus();
8
// roamUser.getLocationListenerStatus();
9
// roamUser.getLocationEvents();
10
// roamUser.getGeofenceEvents();
11
// roamUser.getMovingGeofenceEvents();
12
// roamUser.getTripsEvents();
13
}
14
15
@Override
16
public void onFailure(RoamError roamError) {
17
// Access error code & message below
18
// roamError.getCode();
19
// roamError.getMessage();
20
}
21
});
Copied!
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.
1
<application>
2
...
3
<receiver android:name=".LocationReceiver"
4
android:enabled="true"
5
android:exported="false">
6
<intent-filter>
7
<action android:name="com.roam.android.RECEIVED"/>
8
</intent-filter>
9
</receiver>
10
...
11
</application>
Copied!
Then add the code to the receiver.
Kotlin
Java
1
public class LocationReceiver : RoamReceiver() {
2
override fun onLocationUpdated(context: Context, roamLocation: RoamLocation) {
3
// receive own location updates here
4
// do something with location data using location
5
}
6
7
override fun onLocationReceived(context: Context, roamLocationReceived: RoamLocationReceived) {
8
// receive other user's location updates here
9
// do something with location
10
}
11
12
override fun onEventReceived(context: Context, roamEvent: RoamEvent) {
13
//access event data here
14
}
15
16
override fun onReceiveTripStatus(context: Context, listener: TripStatusListener) {
17
// receive real time trip status here
18
// do something with trip status data
19
}
20
21
override fun onError(context: Context, roamError: RoamError) {
22
//access error data here
23
}
24
}
Copied!
1
public class LocationReceiver extends RoamReceiver {
2
3
@Override
4
public void onLocationUpdated(Context context, RoamLocation roamLocation) {
5
// receive own location updates here
6
// do something with location data using location
7
}
8
9
@Override
10
public void onLocationReceived(Context context, RoamLocationReceived roamLocationReceived) {
11
// receive other user's location updates here
12
// do something with location
13
}
14
15
@Override
16
public void onEventReceived(Context context, RoamEvent roamEvent) {
17
//access event data here
18
}
19
20
@Override
21
public void onReceiveTripStatus(Context context, TripStatusListener listener) {
22
// receive real time trip status here
23
// do something with trip status data
24
}
25
26
@Override
27
public void onError(Context context, RoamError roamError) {
28
//access error data here
29
}
30
}
Copied!
Last modified 4mo ago