Pub/Sub Locations

Creating Users

Once the SDK is initialised, you 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 to login and access developer APIs. We call this Cyprinus user_Id.
1
Roam.createUser("YOUR-USER-DESCRIPTION-GOES-HERE") {(RoamUser, Error) in
2
// Access Roam user data below
3
// RoamUser?.userId
4
// RoamUser?.description
5
// RoamUser?.locationListener
6
// RoamUser?.eventsListener
7
// RoamUser?.locationEvents
8
// RoamUser?.geofenceEvents
9
// RoamUser?.tripsEvents
10
// RoamUser?.nearbyEvents
11
12
// Access error code & message below
13
// Error?.code
14
// Error?.message
15
}
Copied!
The option user description can be used to update 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 information like an email or phone number.
You can always set or update user descriptions later using the below code.
1
Roam.setDescription("SET-USER-DESCRIPTION-HERE")
Copied!

Get User

If you already have a Cyprinus user_ID which you would like to reuse instead of creating a new user, use the code below to get a user session.
1
Roam.getUser("YOUR-ROAM-USER-ID") {(RoamUser, Error) in
2
// Access Roam user data below
3
// RoamUser?.userId
4
// RoamUser?.description
5
// RoamUser?.locationListener
6
// RoamUser?.eventsListener
7
// RoamUser?.locationEvents
8
// RoamUser?.geofenceEvents
9
// RoamUser?.tripsEvents
10
// RoamUser?.nearbyEvents
11
12
// Access error code & message below
13
// Error?.code
14
// Error?.message
15
}
Copied!

Location Tracking

Start Tracking

To publish and subscribe to location data, startSelfTracking methods has to be changed to startTracking
1
Roam.startTracking(TrackingMode)
Copied!
Use the tracking modes while you use the startTracking method Roam.startTracking

Tracking Modes

You can now start tracking your users. Cyprinus has three default tracking modes along with a custom version. They are different based on the frequency of location updates and battery consumption. The higher the frequency, the higher the battery consumption.
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
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 which allows you to customize and build your own tracking mode as per your requirement.
Type
Unit
Unit Range
Distance Interval
Meters
1m ~ 2500m
Distance between location updates example code:
1
// Define a custom tracking method
2
let trackingMethod = RoamTrackingCustomMethods()
3
4
// Update the settings for the created method as per need
5
trackingMethod.activityType = .fitness
6
trackingMethod.pausesLocationUpdatesAutomatically = true
7
trackingMethod.showsBackgroundLocationIndicator = true
8
trackingMethod.useSignificant = false
9
trackingMethod.useRegionMonitoring = false
10
trackingMethod.useVisits = false
11
trackingMethod.accuracyFilter = 10
12
trackingMethod.desiredAccuracy = .kCLLocationAccuracyNearestTenMeters
13
14
// Update the distance intervel as per the use case in meters
15
trackingMethod.distanceFilter = 10
16
17
// Start the tracking with the above created custom tracking method
18
Roam.startTracking(.custom, options: trackingMethod)
Copied!
Time between location updates example code:
1
// Define a custom tracking method
2
let trackingMethod = RoamTrackingCustomMethods()
3
4
// Update the settings for the created method as per need
5
trackingMethod.activityType = .fitness
6
trackingMethod.pausesLocationUpdatesAutomatically = true
7
trackingMethod.showsBackgroundLocationIndicator = true
8
trackingMethod.useSignificant = false
9
trackingMethod.useRegionMonitoring = false
10
trackingMethod.useVisits = false
11
trackingMethod.accuracyFilter = 10
12
trackingMethod.desiredAccuracy = .kCLLocationAccuracyNearestTenMeters
13
14
// Update the time intervel as per the use case in seconds
15
trackingMethod.updateInterval = 10
16
17
// Start the tracking with the above created custom tracking method
18
Roam.startTracking(.custom, options: trackingMethod)
Copied!

Stop Tracking

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

Publish Messages

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.
1
let locationData = RoamPublish()
2
Roam.publishSave(locationData)
Copied!
To stop publishing the location data to other clients.
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

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

UnSubscribe

1
Roam.unSubscribe(TYPE, "ROAM-USER-ID");
Copied!
Type
Description
RoamSubscribe.Events
Subscribe to your own events.
RoamSubscribe.Location
Subscribe to your own location (or) other user's location updates.
RoamSubscribe.Both
Subscribe to your own events and location (or) other user's location updates.

Location Listener

Listeners are needed to consume the location or event data from the SDK iteself. In order to enable listerners, the below setps are needed.
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 toggle the location and event listener to true. 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.
1
Roam.toggleListener(Events: true, Locations: true) {(RoamUser, Error) in
2
// Access Roam user data below
3
// RoamUser?.userId
4
// RoamUser?.description
5
// RoamUser?.locationListener
6
// RoamUser?.eventsListener
7
// RoamUser?.locationEvents
8
// RoamUser?.geofenceEvents
9
// RoamUser?.tripsEvents
10
// RoamUser?.nearbyEvents
11
12
// Access error code & message below
13
// Error?.code
14
// Error?.message
15
}
Copied!
You can also get the current status of listeners with the below method.
1
Roam.getListenerStatus() {(RoamUser, Error) in
2
// Access Roam user data below
3
// RoamUser?.userId
4
// RoamUser?.description
5
// RoamUser?.locationListener
6
// RoamUser?.eventsListener
7
// RoamUser?.locationEvents
8
// RoamUser?.geofenceEvents
9
// RoamUser?.tripsEvents
10
// RoamUser?.nearbyEvents
11
12
// Access error code & message below
13
// Error?.code
14
// Error?.message
15
}
Copied!
To listen to events on the server-side, you should enable events for the user using the below method.
1
Roam.toggleEvents(Geofence: true, Location: true, Trips: true, MovingGeofence: true { (RoamUser, Error) in
2
// Access Roam user data below
3
// RoamUser?.userId
4
// RoamUser?.description
5
// RoamUser?.locationListener
6
// RoamUser?.eventsListener
7
// RoamUser?.locationEvents
8
// RoamUser?.geofenceEvents
9
// RoamUser?.tripsEvents
10
// RoamUser?.nearbyEvents
11
12
// Access error code & message below
13
// Error?.code
14
// Error?.message
15
}
Copied!
Once the listener toggles are set to true, to listen to location updates create a class that implements RoamDelegate and then call Roam.delegate.
Set your RoamDelegate in a code path that will be initialized and executed in the background. For example, make your AppDelegate implement RoamDelegate, not a ViewController. AppDelegate will be initialized in the background, whereas a ViewController may not be.
1
import UIKit
2
import Roam
3
import CoreLocation
4
5
@main
6
class AppDelegate: UIResponder, UIApplicationDelegate, RoamDelegate {
7
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
8
Roam.delegate = self
9
Roam.initialize("YOUR-SDK-KEY-GOES-HERE")
10
return true
11
}
12
func didUpdateLocation(_ location: RoamLocation) {
13
// Do something with the user location
14
}
15
func didReceiveEvents(_ events: RoamEvents) {
16
// Do smoething with user events
17
}
18
func didReceiveUserLocation(_ location: RoamLocationReceived) {
19
// Do something with location of other users' subscribed location
20
}
21
func didReceiveTripStatus(_ tripStatus: TripStatusListener) {
22
//do something with trip status data
23
}
24
}
Copied!
Last modified 4mo ago