Explore the Trips v2 SDK Methods for Android
Explore how to create a trip on Android with Trips v2.
To create a trip, you need to create an object for the trip and assign it with the RoamTrip() builder class. Below are the parameters and their descriptions for the trip object.
metadata
JSONObject
A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
tripName
String
The name of the trip
tripDescription
String
The description for the trip
isLocal
boolean
Value determining if the trip is a local trip.
user
String
The user ID
Stops
List <RoamTripStops>
The list of stop object
When you create a trip, you can add stop locations which are nothing but locations where the user taking the trip will receive events for entry and exit. To create and assign stops to a trip, create objects for a single or multiple stops and assign them with the RoamTripStops() class. Below are the parameters and their descriptions for the stop object.
metadata
JSONObject
A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
stopName
String
The stop name
stopDescription
String
The stop description
geometryRadius
Double
The stop radius
geometry
List<Double>
The coordinates list with longitude and latitude.
address
String
The stop address
Below is an example code for creating a trip with two stops. Let's create our stop objects.
JSONObject metadata = new JSONObject();
metadata.put("Key", "value");
List<Double> geometry1 = new ArrayList<>();
geometry1.add(23.5155215);
geometry1.add(85.30614739);
List<Double> geometry2 = new ArrayList<>();
geometry2.add(12.9716);
geometry2.add(77.5946);
RoamTripStops stop1 = new RoamTripStops();
stop1.setMetadata(metadata);
stop1.setStopDescription("description");
stop1.setStopName("name");
stop1.setAddress("address");
stop1.setGeometryRadius(100.0);
stop1.setGeometry(geometry1);
RoamTripStops stop2 =new RoamTripStops();
stop2.setStopId("");
stop2.setMetadata(metadata);
stop2.setStopDescription("description");
stop2.setStopName("name");
stop2.setAddress("address");
stop2.setGeometryRadius(600.0);
stop2.setGeometry(geometry2);
List<RoamTripStops> stop = new ArrayList<>();
stop.add(stop1);
stop.add(stop2);
val metadata = JSONObject()
metadata.put("Key", "value")
val geometry1: MutableList<Double> = ArrayList()
geometry1.add(23.5155215)
geometry1.add(85.30614739)
val geometry2: MutableList<Double> = ArrayList()
geometry2.add(12.9716)
geometry2.add(77.5946)
val stop1 = RoamTripStops()
stop1.setMetadata(metadata)
stop1.setStopDescription("description")
stop1.setStopName("name")
stop1.setAddress("address")
stop1.setGeometryRadius(100.0)
stop1.setGeometry(geometry1)
val stop2 = RoamTripStops()
stop2.setStopId("")
stop2.setMetadata(metadata)
stop2.setStopDescription("description")
stop2.setStopName("name")
stop2.setAddress("address")
stop2.setGeometryRadius(600.0)
stop2.setGeometry(geometry2)
val stop: MutableList<RoamTripStops> = ArrayList()
stop.add(stop1)
stop.add(stop2)Now, let's create an object for the trip and update the parameters along with stop which was created above.
RoamTrip trip = new RoamTrip.Builder()
.setUserId("userId")
.setMetadata(metadata)
.setTripDescription("description")
.setTripName("name")
.setIsLocal(true)
.setStop(stop)
.build();val trip: RoamTrip? = RoamTrip.Builder()
.setUserId("userId")
.setMetadata(metadata)
.setTripDescription("description")
.setTripName("name")
.setIsLocal(true)
.setStop(stop)
.build()Now that the trip and stop objects are created, let's create the trip with Roam.createTrip() method.
Roam.createTrip(trip, new RoamTripCallback() {
@Override
public void onSuccess(RoamTripResponse response) {
//get trip details
}
@Override
public void onError(Error error) {
//get error details
}
});Roam.createTrip(trip, object : RoamTripCallback {
override fun onSuccess(response: RoamTripResponse) {
//get trip details
}
override fun onError(error: Error?) {
//get error details
}
})tThe list of responses and error parameters are given below with their descriptions.
To access the status parameters:
response.getCode()
Integer
The response code of the method.
response.getMessage()
String
The response message of the method.
To access the trip response:
getTripDetails().getTripId()
String
Unique identifier for the object.
getTripDetails().getMetadata()
Object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
getTripDetails().getTripName()
String
The name of the trip
getTripDetails().getTripDescription()
String
The trip’s description
getTripDetails().getTripState()
String
The current state of the trip is either created, started, or ended.
getTripDetails().getIsLocal()
boolean
Value determining if the trip is a local trip.
getTripDetails().getTotalDistance()
double
The total distance covered by the user for this trip.
getTripDetails().getTotalDuration()
double
The total duration taken by the user for this trip.
getTripDetails().getTotalElevationGain()
double
The total elevation gain covered by the user for this trip.
getTripDetails().createdAt()
String
Timestamp of when the trip was created
getTripDetails().updatedAt()
String
Timestamp of when the trip was updated
getTripDetails().startedAt()
String
Timestamp of when the trip was started by the user
getTripDetails().endedAt()
String
Timestamp of when the trip was ended by the user
To access user details:
getUser().getId()
String
Unique identifier for the object.
getUser().getMetadata()
Object
A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
getUser().getDescription()
String
User description
getUser().getName()
String
The user's full name
To access stop details:
getStops().get(i).getStopName()
String
The stop name
getStops().get(i).getStopDescription()
String
The stop description
getStops().get(i).getMetadata()
Object
A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
getStops().get(i).getGeometryRadius()
double
The stop radius.
getStops().get(i).getGeometry()
Object
The coordinates list with longitude and latitude.
getStops().get(i).getArrivedAt()
String
The timestamp when the user arrived at the stop.
getStops().get(i).getDepartedAt()
String
The timestamp when the user departed from the stop.
getStops().get(i).getAddress()
String
The stop address .
To access error details:
error.getErrorCode()
Integer
The error response code of the method.
error.getErrorMessage()
String
The error response message of the method.
error.getErrorDescription()
String
The error response description of the method.
error.getErrors().get(i).getMessage()
String
The message for error detail.
error.getErrors.get(i).getField()
String
The field for error detail.
Explore how to update a trip on Android with Trips v2.
The Update Trip method allows you to update your trip details at any point in time. However, you can update the stop locations as long as the trip has not started. You need to create a new object or update the existing trip, assign it with the RoamTrip() class and pass the trip object to Roam.updateTrip(trip).
Roam.updateTrip(trip, new RoamTripCallback() {
@Override
public void onSuccess(RoamTripResponse response) {
//get trip details
}
@Override
public void onError(Error error) {
//get error details
}
}); Roam.updateTrip(trip, object : RoamTripCallback {
override fun onSuccess(response: RoamTripResponse) {
//get trip details
}
override fun onError(error: Error?) {
//get error details
}
})The trip response and its parameters are similar to those of the createTrip() method.
There's no need to exclusively specify if the trip is local using a boolean value. The updateTrip() method will check that for you and update the trip details accordingly.
Explore how to start a quick trip on Android with Trips v2.
A Quick Trip creates and starts a trip immediately with a single method. Creating a quick trip is similar to creating a trip.
metadata
JSONObject
A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
tripName
String
Name of the trip
tripDescription
String
Trip description
isLocal
boolean
Value determining if the trip is a local trip.
Along with the above trip object, you need to pass an additional parameter for trackingMode which is optional and defaults to active tracking mode.
Roam.startTrip(trip, RoamTrackingMode.active, new RoamTripCallback() {
@Override
public void onSuccess(RoamTripResponse response) {
//get trip details
}
@Override
public void onError(Error error) {
//get error details
}
}); Roam.startTrip(trip, RoamTrackingMode.ACTIVE, object : RoamTripCallback {
override fun onSuccess(response: RoamTripResponse) {
//get trip details
}
override fun onError(error: Error?) {
//get error details
}
})To start a quick trip in custom tracking mode, refer to the following code snippet block.
RoamTrackingMode roamTrackingMode = new RoamTrackingMode.Builder(distanceFilter, stopDuration)
.setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
.build();
Roam.startTrip(trip, roamTrackingMode, new RoamTripCallback() {
@Override
public void onSuccess(RoamTripResponse response) {
//get trip details
}
@Override
public void onError(Error error) {
//get error details
}
});val roamTrackingMode = RoamTrackingMode.Builder(distanceFilter, stopDuration)
.setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
.build()
Roam.startTrip(trip, roamTrackingMode, object : RoamTripCallback {
override fun onSuccess(response: RoamTripResponse) {
//get trip details
}
override fun onError(error: Error?) {
//get error details
}
})The list of responses and error parameters are given below with their descriptions.
To access the status parameters:
response.getCode()
Integer
The response code of the method.
response.getMessage()
String
The response message of the method.
To access trip responses:
getTripDetails().getTripId()
String
Unique identifier for the object.
getTripDetails().getMetadata()
Object
A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
getTripDetails().getTripName()
String
The trip name
getTripDetails().getTripDescription()
String
The trip’s description
getTripDetails().getTripState()
String
The current state of the trip is either created, started, or ended.
getTripDetails().getIsLocal()
boolean
The value determining if the trip is a local trip.
getTripDetails().getTotalDistance()
double
The total distance covered by the user for this trip.
getTripDetails().getTotalDuration()
double
The total duration taken by the user for this trip.
getTripDetails().getTotalElevationGain()
double
The total elevation gain covered by the user for this trip.
getTripDetails().createdAt()
String
Timestamp of when the trip was created
getTripDetails().updatedAt()
String
Timestamp of when the trip was updated
getTripDetails().startedAt()
String
Timestamp of when the trip was started by the user
getTripDetails().endedAt()
String
Timestamp of when the trip was ended by the user
To access user details:
getUser().getId()
String
Unique identifier for the object.
getUser().getMetadata()
Object
A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
getUser().getDescription()
String
User description
getUser().getName()
String
The user's full name
To access error details:
error.getErrorCode()
Integer
The error response code of the method.
error.getErrorMessage()
String
Error response message of the method.
error.getErrorDescription()
String
Error response description of the method.
error.getErrors().get(i).getMessage()
String
Message for error detail.
error.getErrors.get(i).getField()
String
The field for error detail.
Explore how to start a trip on Android with Trips v2.
The Start Trip method allows you to start a planned trip with the previously created tripID.
Roam.startTrip("tripId", new RoamTripCallback() {
@Override
public void onSuccess(RoamTripResponse response) {
//get trip details
}
@Override
public void onError(Error error) {
//get error details
}
}); Roam.startTrip("tripId", object : RoamTripCallback {
override fun onSuccess(response: RoamTripResponse?) {
//get trip details
}
override fun onError(error: Error?) {
//get error details
}
})The trip response and its parameters are similar to those of the createTrip() method.
Explore how to end a trip on Android with Trips v2.
the End Trip method allows you to end the trip with the previously created tripID. If you want to stop tracking, then you can pass stopTracking as true or false.
Roam.endTrip("tripId",true, new RoamTripCallback() {
@Override
public void onSuccess(RoamTripResponse response) {
//get trip details
}
@Override
public void onError(Error error) {
//get error details
}
}); Roam.endTrip("tripId", true, object : RoamTripCallback {
override fun onSuccess(response: RoamTripResponse) {
//get trip details
}
override fun onError(error: Error?) {
//get error details
}
})The trip response and its parameters are similar to those of the createTrip method.
Explore how to pause a trip on Android with Trips v2.
The pause trip method allows you to pause the trip with the previously created tripID.
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.
Explore how to resume a trip on Android with Trips v2.
The Resume Trip method allows you to resume the trip with the previously paused tripID.
Roam.resumeTrip("tripId", new RoamTripCallback() {
@Override
public void onSuccess(RoamTripResponse response) {
//get trip details
}
@Override
public void onError(Error error) {
//get error details
}
}); Roam.resumeTrip("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.
Explore how to sync a trip on Android with Trips v2.
Sync Trip allows you to sync a local trip to the server by using tripID.
Roam.syncTrip("tripId", new RoamSyncTripCallback() {
@Override
public void onSuccess(RoamSyncTripResponse response) {
//get sync trip details
}
@Override
public void onError(Error error) {
//get error details
}
}); Roam.syncTrip("tripId", object : RoamSyncTripCallback {
override fun onSuccess(response: RoamSyncTripResponse) {
//get sync trip details
}
override fun onError(error: Error?) {
//get error details
}
})You can access the sync trip response parameters below:
response.getCode()
Integer
The success response code of the method.
response.getMessage()
String
The success response message of the method.
response.getDescription()
String
The error response description of the method.
response.getData().getTripId()
String
Unique identifier for the object.
response..getData().getIsSynced()
boolean
The boolean value to determine if the trip is synced.
Explore how to get the details of a trip on Android with Trips v2.
To get the details of the trip anytime, you can use the Roam.getTrip("tripId") method by passing the tripID.
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.
There's no need to exclusively specify if the trip is local or not using a boolean value. The getTrip() method will check that for you and update the trip details accordingly.
Explore how to get a user's active trips on Android with Trips v2.
To get the users' active trips, you can use the Roam.getActiveTrips(isLocal) method where the value of isLocal is boolean. The value being true returns all the local trips and value being false, returns all active trips created on the server side.
Roam.getActiveTrips(isLocal,new RoamActiveTripsCallback() {
@Override
public void onSuccess(RoamActiveTripsResponse response) {
//get active trips details
}
@Override
public void onError(Error error) {
//get error details
}
});Roam.getActiveTrips(isLocal, object : RoamActiveTripsCallback {
override fun onSuccess(response: RoamActiveTripsResponse?) {
//get active trips details
}
override fun onError(error: Error?) {
//get error details
}
})The Get Active trips method returns all the trips in the form of a list. The parameters and responses are similar to those of the createTrip() method.
Explore how to get the summary of a trip on Android with Trips v2.
To get a summary of the trip anytime, you can use the Roam.getTripSummary("tripId") method by passing the tripID.
Roam.getTripSummary("tripId", new RoamTripCallback() {
@Override
public void onSuccess(RoamTripResponse response) {
//get active trip summary details
}
@Override
public void onError(Error error) {
//get error details
}
});Roam.getTripSummary("tripId", object : RoamTripCallback {
override fun onSuccess(response: RoamTripResponse) {
//get active trip summary details
}
override fun onError(error: Error?) {
//get error details
}
}The trip response and its parameters are similar to those of the createTrip() method.
You don't need to mention if the trip is local trip with a boolean value. The getTripSummary() method will check that for you and return the trip details accordingly.
Explore how to subscribe to a trip on Android with Trips v2.
You can subscribe to a trip using the tripID to get real-time trip data.
Roam.subscribeTrip("tripId");Roam.subscribeTrip("tripId")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.
<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 extends RoamReceiver {
@Override
public void onLocationUpdated(Context context, RoamLocation roamLocation) {
super.onLocationUpdated(context, roamLocation);
// receive own location updates here
// do something with location data using location
// 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 onReceiveTrip(Context context, RoamTripStatus roamTripStatus) {
//get realtime trip data
}
@Override
public void onError(Context context, RoamError roamError) {
// receive error message here
// roamError.getCode());
// roamError.getMessage());
}
}
class LocationReceiver : RoamReceiver() {
override fun onLocationUpdated(context: Context?, roamLocation: RoamLocation?) {
super.onLocationUpdated(context, roamLocation)
// receive own location updates here
// do something with location data using location
// 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 fun onReceiveTrip(context: Context?, roamTripStatus: RoamTripStatus?) {
//get realtime trip data
}
override fun onError(context: Context?, roamError: RoamError?) {
// receive error message here
// roamError.getCode())
// roamError.getMessage())
}
}You can access the subscribed trip response parameters below:
roamTripStatus.getTripId()
String
Unique identifier for the object.
roamTripStatus.getSpeed()
double
Current speed of the subscribed trip
roamTripStatus.getDistance()
double
The total distance covered by the user for this trip.
roamTripStatus.getDuration()
double
The total duration taken by the user for this trip.
roamTripStatus.getStartedTime()
String
The timestamp of when the trip was started by the user
roamTripStatus.getPace()
double
The current pace of the subscribed trip
roamTripStatus.getLatitude()
double
Current latitude coordinates of the subscribed trip
roamTripStatus.getLongitude()
double
Current longitude coordinates of the subscribed trip
roamTripStatus.getAltitude()
double
Current altitude of the subscribed trip
roamTripStatus.getElevationGain()
double
The elevation gain covered by the user for this trip.
roamTripStatus.getTotalElevation()
double
The total elevation gain covered by the user for this trip.
You can also unsubscribe from the trip using its tripID.
Roam.unsubscribeTrip("tripId")Explore how to delete a trip on Android with Trips v2.
You can delete the trip irrespective of any trip state. To delete the trip, you need to use the tripID with Roam.deleteTrip("tripId") method.
Roam.deleteTrip("tripId", new RoamDeleteTripCallback() {
@Override
public void onSuccess(RoamDeleteTripResponse response) {
//get delete trip details
}
@Override
public void onError(Error error) {
//get error details
}
}); Roam.deleteTrip("tripId", object : RoamDeleteTripCallback {
override fun onSuccess(response: RoamDeleteTripResponse) {
//get delete trip details
}
override fun onError(error: Error) {
//get error details
}
})You can access the delete trip response parameters below:
response.getCode()
Integer
The success response code of the method.
response.getMessage()
String
The success response message of the method.
response.getDescription()
String
Error response description of the method.
response.getTrip().getTripId()
String
Unique identifier for the object.
response..getTrip().getIsDeleted()
boolean
Boolean value to determine if the trip has been deleted.