All pages
Powered by GitBook
1 of 20

SDK Methods (iOS)

Explore all of Roam's iOS SDK methods.

SDK Configuration (iOS)Update Current Location (iOS)Update Location When Stationary (iOS)Get Current Location (iOS)Trips v1 SDK Methods (iOS)

SDK Configuration (iOS)

The first step is to configure the iOS SDK.

Set Tracking in AppState

Roam.setTrackingInAppState(STATE)
[Roam setTrackingInAppState:STATE];

Parameter

Description

STATE

RoamTrackingState.Foreground (or) RoamTrackingState.Background (or)

RoamTrackingState.AlwaysOn

Offline Location Tracking

Roam.offlineLocationTracking(Bool)
[Roam offlineLocationTracking];

Parameter

Description

Bool

true (default) -- Offline location enabled. false -- Offline location disabled.

Accuracy Engine

For enabling accuracy engine for Passive, Active, and Balanced tracking,

Roam.enableAccuracyEngine()

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

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

For disabling accuracy engine,

Roam.disableAccuracyEngine()

Get Current Location (iOS)

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

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

Roam.getCurrentLocation(accuracy) { (location, error) in
    //location?.coordinate.latitude           
    //location?.coordinate.longitude       
    //location?.altitude
    //  error?.code
    //  error?.message 
}
 [Roam getCurrentLocation:accuracy handler:^(CLLocation * location, RoamError * error) {
          //  location?.coordinate.latitude           
          //  location?.coordinate.longitude       
          //  location?.altitude
          //  error?.code
          //  error?.message 
    }];

Update Current Location (iOS)

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

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

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

// update current location without meta-data
Roam.updateCurrentLocation(accuracy)

// update the current location with meta-data
// Declare meta-data
let publish = RoamPublish()
let metaData:Dictionary<String,Any> = ["key":value]
publish.meta_data = metaData
Roam.updateCurrentLocation(accuracy, publish)
// update current location without meta-data
[Roam updateCurrentLocation:accuracy];

// update current location with meta-data
// Declare meta-data
RoamPublish *publish = [[RoamPublish alloc] init];
NSDictionary *metaData = @{ "key" : "value"};
publish.meta_data = metaData
[Roam updateCurrentLocation:accuracy :publish];

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

Update Location When Stationary (iOS)

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

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

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

Roam.updateLocationWhenStationary(interval-in-seconds)
[Roam updateLocationWhenStationary:<#(interval-in-seconds)#>];

Trips v1 SDK Methods (iOS)

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

Quick Start & End Trip

The SDK can start a quick trip with a single function which accepts optional values for tracking modes, origin and destinations.

// tripId as String
// localTrip as Bool
// RoamTrackingMode
// tripDescription as string
// origin as Array<Array<Double>> [[latitude,longitude],[latitude,longitude]]
// destination as Array<Array<Double>> [[latitude,longitude],[latitude,longitude]]
// option for custom tracking RoamTrackingCustomMethods
​
Roam.startTrip("tripId", false, RoamTrackingMode.active, "tripDescription", origins, destination ) { startTrip, error in
            //   access roam trip created timestamp with roamTrip?.createdAt
          //   access roam trip user id with roamTrip?.userId
          //   access roam trip id with roamTrip?.tripId
          //   access roam error code with roamError?.code
         //   access roam error message with roamError?.message   
}
// tripId as String
// localTrip as Bool
// RoamTrackingMode
// tripDescription as string
// origin as Array<Array<Double>> [[latitude,longitude],[latitude,longitude]]
// destination as Array<Array<Double>> [[latitude,longitude],[latitude,longitude]]
// option for custom tracking RoamTrackingCustomMethods
 [Roam startTrip:@"tripId" :BOOL :RoamTrackingModeActive :@"tripDescription" :origins :destination :RoamTrackingCustomMethods handler:^(RoamStartTrip * startTrip, RoamError * error) {
        
  }];

You can now stop the trip and control the tracking modes directly from the stop trip method. This allows you to either force stop location tracking or change the tracking mode using the stop trip method.

// tripId as String
// forceStopTracking as Bool
// RoamTrackingMode
// option for custom tracking RoamTrackingCustomMethods
    Roam.stopTrip("tripId", forceStopTracking: true, RoamTrackingMode, RoamTrackingCustomMethods) { roamStatus, roamError in
                                                                                                   
           //   access trip status with roamStatus                                                                                        
          //   access roam error code with roamError?.code
         //   access roam error message with roamError?.message                                                                      
        }
  [Roam stopTrip:@"" forceStopTracking:false :RoamTrackingModeActive :RoamTrackingCustomMethods handler:^(NSString * status, RoamError * error) {
        
    }];

You can also use the below methods to manually create a trip and then use the tripID to start the trip.

Create Trip

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

Roam.createTrip(Bool, nil) { (roamTrip, roamError) in
          //   access roam trip created timestamp with roamTrip?.createdAt
          //   access roam trip user id with roamTrip?.userId
          //   access roam trip id with roamTrip?.tripId
          //   access roam error code with roamError?.code
         //   access roam error message with roamError?.message            
}
[Roam createTrip:true :nil handler:^(RoamCreateTrip * roamTrip, RoamError * roamError) {
             //   access roam trip created timestamp with roamTrip?.createdAt
             //   access roam trip user id with roamTrip?.userId
             //   access roam trip id with roamTrip?.tripId
            //   access roam error code with roamError?.code
            //   access roam error message with roamError?.message       
}];

Get Trip Details

Roam.getTripDetails("ROAM-TRIP-ID") { (roamTrip, roamError) in
            //   access roam trip created timestamp with roamTrip?.createdAt
            //   access roam trip user id with roamTrip?.userId
            //   access roam trip id with roamTrip?.tripId
            //   access roam error code with roamError?.code
            //   access roam error message with roamError?.message
  }
 [Roam getTripDetails:@"ROAM-TRIP-ID" handler:^(RoamGetTrip * roamTrip, RoamError * roamError) {
            //   access roam trip created timestamp with roamTrip?.createdAt
            //   access roam trip user id with roamTrip?.userId
            //   access roam trip id with roamTrip?.tripId
            //   access roam error code with roamTrip?.code
            //   access roam error message with roamError?.message  
  }];

Start and Stop Trip

Start Trip

Start trip starts the trip with the previously created tripID.

Roam.startTrip("ROAM-TRIP-ID") { (status, roamError) in
             //   access roam trip status with status
            //   access roam error code with roamError?.code
            //   access roam error message with roamError?.message
}
[Roam startTrip:@"ROAM-TRIP-ID" :@"ROAM-TRIP-DESC" handler:^(NSString * status, RoamError * roamError) {
            //   access roam trip status with status
            //   access roam error code with roamError?.code
            //   access roam error message with roamError?.message  
}];

Stop Trip

Roam.stopTrip("ROAM-TRIP-ID") { (status, roamError) in
             //   access roam trip status with status
            //   access roam error code with roamError?.code
            //   access roam error message with roamError?.message
}
[Roam stopTrip:@"ROAM-TRIP-ID" handler:^(NSString * status, RoamError * roamError) {
             //   access roam trip status with status
            //   access roam error code with roamError?.code
            //   access roam error message with roamError?.message  
  }];

Pause and Resume Trip

Pause Trip

Pause trip pauses a previously started trip with its tripID.

Roam.pauseTrip("ROAM-TRIP-ID") { (status, error) in
            //   access roam trip status with status
            //   access roam error code with roamError?.code
            //   access roam error message with roamError?.message
}
 [Roam pauseTrip:@"ROAM-TRIP-ID" handler:^(NSString * status, RoamError * roamError) {
                    //   access roam trip status with status
            //   access roam error code with roamError?.code
            //   access roam error message with roamError?.message  
  }];

Resume Trip

Resume trip resumes a previously paused trip.

Roam.resumeTrip("ROAM-TRIP-ID") { (status, roamError) in
            //   access roam trip status with status
            //   access roam error code with roamError?.code
            //   access roam error message with roamError?.message
}
[Roam resumeTrip:@"ROAM-TRIP-ID" handler:^(NSString * status, RoamError * roamError) {
             //   access roam trip status with status
            //   access roam error code with roamError?.code
            //   access roam error message with roamError?.message   
  }];

Subscribe to Trip Status

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

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

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

// unsubscribe from all the trip 
Roam.unsubscribeTripStatus()

// unsubscribe from trip
Roam.unsubscribeTripStatus('ROAM-TRIP-ID')
// unsubscribe from all the trip  
[Roam unsubscribeTripStatus:NULL];
    
// unsubscribe from trip 
[Roam unsubscribeTripStatus:@"ROAM-TRIP-ID"];

Get Trip Status

Roam.getTripStatus("ROAM-TRIP-ID") { (roamTrip, roamError) in
            //   access roam trip distance covered with roamTrip?.distance
            //   access roam trip speed with roamTrip?.speed
            //   access roam trip duration with roamTrip?.duration
            //   access roam trip id with roamTrip?.tripId
            //   access roam trip started timestamp with roamTrip?.startedAt
            //   access roam error code with roamError?.code
            //   access roam error message with roamError?.message
  }
  [Roam getTripStatus:@"ROAM-TRIP-ID" handler:^(RoamTripListener * roamTrip, RoamError * roamError) {
            //   access roam trip distance covered with roamTrip?.distance
            //   access roam trip speed with roamTrip?.speed
            //   access roam trip duration with roamTrip?.duration
            //   access roam trip id with roamTrip?.tripId
            //   access roam trip started timestamp with roamTrip?.startedAt
            //   access roam error code with roamError?.code
            //   access roam error message with roamError?.message
  }];

Get Trip Summary

Roam.getTripSummary("ROAM-TRIP-ID") { (roamTrip, roamError) in
            //   access roam trip distance covered with roamTrip?.distanceCovered
            //   access roam trip route with roamTrip?.route
            //   access roam trip duration with roamTrip?.duration
            //   access roam trip id with roamTrip?.tripId
            //   access roam error code with roamError?.code
            //   access roam error message with roamError?.message
  }
[Roam getTripSummary:@"ROAM-TRIP-ID" handler:^(RoamTripSummary * roamTrip, RoamError * roamError) {
            //   access roam trip distance covered with roamTrip?.distanceCovered
            //   access roam trip route with roamTrip?.route
            //   access roam trip duration with roamTrip?.duration
            //   access roam trip id with roamTrip?.tripId
            //   access roam error code with roamError?.code
            //   access roam error message with roamError?.message 
}];

Trips v2 SDK Methods (iOS)

Explore the Trips v2 SDK Methods for 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)

Create Trip (iOS)

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

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

Parameter
Type
Description
Optional

metadata

dictionary

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

tripDescription

string

The trip’s description

isLocal

boolean

The value determining if the trip is a local trip.

user

string

The user object

stops

array

The list of stop object

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

Parameter
Type
Description
Optional

metadata

dictionary

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

number

The stop radius

geometryCoordinates

array

Coordinates with longitude, latitude.

address

string

The stop address

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

let stop = RoamTripStop()
        
stop.address = "address"
stop.metadata = ["key":"value"]
stop.stopName = "name"
stop.stopDescription = "description"
stop.geometryRadius = 100
// logitude , latitude
stop.geometryCoordinates = [10.1,10.1]
    RoamTripStop *stop = [[RoamTripStop alloc] init];
    [stop setAddress:@"address"];
    [stop setMetadata:@{@"key": @"value"}];
    [stop setStopDescription:@"description"];
    [stop setGeometryRadius:@100];
    // logitude , latitude
    [stop setGeometryCoordinates:@[@10.1,@10.1]];

Now, let's create a trip object and update the parameters along with the stop created above.

let trip = RoamTrip()
        
trip.user = "userId"
trip.metadata = ["key":"value"]
trip.tripName = "name"
trip.tripDescription = "description"
trip.isLocal = true
trip.stops = [stop]
  RoamTrip *trip = [[RoamTrip alloc] init];
  [trip setMetadata:@{@"key": @"value"}];
  [trip setTripName:@"name"];
  [trip setTripDescription:@"description"];
  [trip setIsLocal:true];
  [trip setStops:@[stop]];

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

Roam.createTrip(trip) {response,error in
            // Access status
            // response?.code
            // response?.message
            
            // To access trip details
            let tripDetails = response?.trip
            // Access trip details parameter with tripDetails object
            
            // To access trip user details
            let user = tripDetails?.user
            // Access trip user details parameter with user object
            
            // To access stop details
            let stops = tripDetails?.stops
            //  Access trip stop details parameter with stops array
    
}
[Roam createTrip:trip handler:^(RoamTripResponse * response, RoamTripError * error) {
            // Access status
            // response?.code
            // response?.message
            
            // To access trip details
            RoamTrip  *tripDetails = response.trip;
            // Access trip details parameter with tripDetails object
            
            // To access trip user details
            RoamUser * user = tripDetails.user
            // Access trip user details parameter with user object
            
            // To access stop details
            RoamTripStop *stops = tripDetails.stops;
            //  Access trip stop details parameter with stops array

}];

The list of responses, error parameters and their description is given below.

To access status parameters:

Parameter
Type
Description

response?.code

number

The response code of the method.

response?.message

string

The response message of the method.

To access trip response:

Parameter

Type

Description

tripDetails?.tripId

number

Unique identifier for the trip object.

tripDetails?.metadata

dictionary

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.

tripDetails?.tripName

string

The trip name

tripDetails?.tripDescription

string

The trip description

tripDetails?.tripState

string

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

tripDetails?.isLocal

boolean

Value determining if the trip is a local trip.

tripDetails?.totalDistance

number

The total distance covered by the user for this trip.

tripDetails?.totalDuration

number

The total duration taken by the user for this trip.

tripDetails?.totalElevationGain

number

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

tripDetails?.createdAt

string

Timestamp of when the trip was created

tripDetails?.updatedAt

string

Timestamp of when the trip was updated

tripDetails?.startedAt

string

Timestamp when the trip was started by the user

tripDetails?.endedAt

string

Timestamp when the trip was ended by the user

To access user details:

Parameter

Type

Description

user?.userId

string

Unique identifier for the user object.

user?.metadata

dictionary

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.

user?.userDescription

string

User description

user?.userName

string

User's full name

To access stop details:

Parameter

Type

Description

stops?[i].stopName

string

The stop name

stops?[i].stopDescription

string

The stop description

stops?[i].metadata

dictionary

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.

stops?[i].geometryRadius

string

The stop radius

stops?[i].geometryCoordinates

array

Coordinates with longitude , latitude.

stops?[i].arrivedAt

string

Timestamp of when the user arrived at the stop

stops?[i].departedAt

string

Timestamp of when the user departed from the stop

stops?[i].address

string

The stop address

To access the error details:

Parameter

Type

Description

error?.code

number

The error response code of the method.

error?.message

string

The error response message of the method.

error?.errorDescription

string

The error response description of the method.

errorDetails?[i].message

string

The message for error details.

errorDetails?[i].field

string

The field for error details.

Update Trip (iOS)

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

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

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

Roam.updateTrip(trip) { response, error in
    // Access trip response and error here            
}
[Roam updateTrip handler:^(RoamTripResponse * response, RoamTripError * error) {
       // Access trip response and error here            
}];

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

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

Start Quick Trip (iOS)

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

The Start Quick Trip method creates and starts a trip immediately.

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

Parameter
Optional

metadata

dictionary

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) { response, error in
    // Access trip response and error here
}
[Roam startTrip:trip :RoamTrackingModeActive :NULL handler:^(RoamTripResponse * response, RoamTripError * error) {
       // Access trip response and error here
}];

To start a quick trip with custom tracking mode, refer to the following code:

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

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

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

Roam.startTrip(trip, RoamTrackingMode.custom, customTrackingMode ) { response, error in
    // Access trip response and error here
}
RoamTrackingCustomMethodsObjcWrapper *customTrackingMode = [[RoamTrackingCustomMethodsObjcWrapper alloc] init];
[customTrackingMode setUpCustomOptionsWithDesiredAccuracy:LocationAccuracyKCLLocationAccuracyBest
                            useVisit:false showsBackgroundLocationIndicator:true
                            distanceFilter:10 useSignificant:false
                            useRegionMonitoring:false useDynamicGeofencRadius:false
                            geofenceRadius:0 allowBackgroundLocationUpdates:true
                            activityType:CLActivityTypeFitness pausesLocationUpdatesAutomatically:true
                            useStandardLocationServices:false accuracyFilter:10 updateInterval:10];
    
[Roam startTracking:RoamTrackingModeCustom options:customTrackingMode];

The list of responses, error parameters and their description is given below.

To access the status parameters:

Parameter
Type
Description

response?.code

number

The response code of the method.

response?.message

string

The response message of the method.

To access trip response:

Parameter
Type
Description

tripDetails?.tripId

number

Unique identifier for trip objects.

tripDetails?.metadata

dictionary

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.

tripDetails?.tripName

string

Name of the trip.

tripDetails?.tripDescription

string

Trip description

tripDetails?.tripState

string

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

tripDetails?.isLocal

boolean

Value determining if the trip is a local trip.

tripDetails?.totalDistance

number

The total distance covered by the user for this trip.

tripDetails?.totalDuration

number

The total duration taken by the user for this trip.

tripDetails?.totalElevationGain

number

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

tripDetails?.createdAt

string

Timestamp of wen the trip was created

tripDetails?.updatedAt

string

Timestamp of when the trip was updated

tripDetails?.startedAt

string

Timestamp of when the trip was started by the user

tripDetails?.endedAt

string

Timestamp of when the trip was ended by the user

To access user details:

Parameter
Type
Description

user?.userId

string

Unique identifier for the user object.

user?.metadata

dictionary

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.

user?.userDescription

string

User description

user?.userName

string

User's full name

To access error details:

Parameter
Type
Description

error?.code

number

The error response code of the method.

error?.message

string

The error response message of the method.

error?.errorDescription

string

The error response description of the method.

errorDetails?[i].message

string

The message for error detail.

errorDetails?[i].field

string

The field for error detail.

Start Trip (iOS)

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

To start a planned trip, you need to pass the tripID with theRoam.endTrip("tripId") method.

Roam.startTrip("tripId") { response, error in
  // Access end trip response
}
[Roam startTrip:@"tripId" :false handler:^(RoamTripResponse * response, RoamTripError * error) {
  // Access end trip response    
}];

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

End Trip (iOS)

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

To end the trip, you need to pass the tripID with the Roam.endTrip("tripId") method.

Roam.endTrip("tripId") { response, error in
  // Access end trip response
}
[Roam endTrip:@"tripId" :false handler:^(RoamTripResponse * response, RoamTripError * error) {
  // Access end trip response    
}];

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

Pause Trip (iOS)

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

To pause the trip, you need to pass the tripID with the Roam.pauseTrip("tripId") method.

Roam.pauseTrip("tripId") { response, error in
  // Access resume trip response
}
[Roam pauseTrip:@"tripId" handler:^(RoamTripResponse * response, RoamTripError * error) {
     // Access resume trip response   
}];

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

Resume Trip (iOS)

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

To resume the trip, you need to pass the tripID with the Roam.resumeTrip("tripId") method.

Roam.resumeTrip("tripId") { response, error in
  // Access resume trip response
}
[Roam resumeTrip:@"tripId" handler:^(RoamTripResponse * response, RoamTripError * error) {
     // Access resume trip response   
}];

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

Sync Trip (iOS)

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

To sync a trip, you need to pass the tripID with the Roam.syncTrip("tripId") method.

Roam.syncTrip("tripId") { response, error in
  // Access sync trip response
}
[Roam syncTrip:@"" handler:^(RoamTripSync * response, RoamTripError * error) {
 // Access sync trip response
}];

You can access the sync trip response parameters below:

Parameter
Type
Description

response?.code

number

The success response code of the method.

response?.message

string

The success response message of the method.

response?.messageDescription

string

Error response description of the method.

response?.tripId

string

Unique identifier for the trip object.

response?.isSynced

boolean

Boolean value to determine if the trip is synced.

Get Trip (iOS)

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

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

Roam.getTrip("tripId") { response, error in
    // Access trip response and error here
}
[Roam getTrip:@"tripId" handler:^(RoamTripResponse * response, RoamTripError * error) {
      // Access trip response and error here
}];

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

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

Get Active Trips (iOS)

Explore how to get a user's active trips on iOS 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(true) { response, error in
      // Access trip response and error here         
}
[Roam getActiveTrips:true handler:^(RoamActiveTripResponse * _Nullable, RoamTripError * _Nullable) {
        // Access trip response and error here         
}];

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

Get Trip Summary (iOS)

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

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

Roam.getTripSummary("tripId") { response, error in
    // Access trip response and error here
}
[Roam getTripSummary:@"tripId" handler:^(RoamTripResponse * response, RoamTripError * error) {
      // Access trip response and error here
}];

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

Subscribe Trip (iOS)

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

For you to subscribe to a trip, you need to pass the tripID with the Roam.subscribeTrip("tripId") method.

Roam.subscribeTrip("tripId")
[Roam subscribeTrip:@"tripId"];

Once you subscribe to the trip, you will receive real time trip data in the listener methods

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

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

Set your RoamDelegate in a code path that will be initialized and executed in the background. For example, ensure that your AppDelegate and not the ViewController implements RoamDelegate. The reason being, AppDelegate will be initialized in the background, whereas a ViewController may not be.

Note: For tracking without user sessions, i.e., self tracking, you can only listen to location, errors and offline trip status data since the locations are not being sent to our servers for event processing.

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 
    }
    func onReceiveTrip(_ response: RoamTripStatus) {
        // Access subscribeTrip response
    }
- (void)onReceiveTrip:(RoamTripStatus *)tripStatus {
// Access subscribeTrip response
}

You can access the subscribed trip response parameters below:

Parameter
Type
Description

response.tripId

string

Unique identifier for trip objects.

response.speed

double

Current speed of the subscribed trip

response.distance

double

Current distance covered of the subscribed trip

response.duration

double

Current duration taken of the subscribed trip

response.startedTime

string

Timestamp of when the trip was started by the user

response.pace

double

The current pace of the subscribed trip

response.latitude

double

Current latitude coordinates of the subscribed trip

response.longitude

double

Current longitude coordinates of the subscribed trip

You can unsubscribe from trips using the tripID.

Roam.unsubscribeTrip("tripId")
[Roam unsubscribeTrip:@"tripId"];

Delete Trip (iOS)

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

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

Roam.deleteTrip("tripId") { response, error in
    // Access delete trip response
}
[Roam deleteTrip:@"tripId" handler:^(RoamTripResponse * response, RoamTripError * error) {
      // Access delete trip response  
}];

You can access the delete trip response parameters below:

Parameter
Type
Description

response?.code

number

The success response code of the method.

response?.message

string

The success response message of the method.

response?.errorDescription

string

Error response description of the method.

response?.tripId

string

Unique identifier for trip objects.

response?.isDeleted

boolean

Boolean value to determine if the trip has been deleted.