Pub/Sub Locations
User sessions are mandatory for pub/sub tracking. Without user sessions, location tracking will continue to work as self tracking and pub/sub methods will return error callbacks.
Once the SDK is initialized, you 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 to login and access developer APIs. We call this the Roam
user_Id
. // create user with meta-data and description
// Declare meta-data as dictionary
// Description as string
let metaData:Dictionary<String,Any> = ["key":value]
Roam.createUser("YOUR-USER-DESCRIPTION-GOES-HERE", metaData) {(RoamUser, Error) in
// Access Roam user data below
// RoamUser?.userId
// RoamUser?.description
// RoamUser?.locationListener
// RoamUser?.eventsListener
// RoamUser?.locationEvents
// RoamUser?.geofenceEvents
// RoamUser?.tripsEvents
// RoamUser?.nearbyEvents
// RoamUser?.metaData
// Access the error code & message below
// Error?.code
// Error?.message
}
The "user description" option 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 ID or phone number.
You can always set or update user descriptions and meta-data later using the code below.
Swift
Objective-C
// update user with meta-data and description
// Declare meta-data as dictionary
// Description as string
let metaData:Dictionary<String,Any> = ["key":value]
Roam.updateUser("Description", metaData)
// update user with meta-data and description
// Declare meta-data as dictionary
// Description as string
[Roam updateUser:@"userDescription" :@"metadata"];
If you already have a Roam
user_ID
that you would like to reuse instead of creating a new user, use the code below to get a user session.Roam.getUser("YOUR-ROAM-USER-ID") {(RoamUser, Error) in
// Access Roam user data below
// RoamUser?.userId
// RoamUser?.description
// RoamUser?.locationListener
// RoamUser?.eventsListener
// RoamUser?.locationEvents
// RoamUser?.geofenceEvents
// RoamUser?.tripsEvents
// RoamUser?.nearbyEvents
// Access error code & message below
// Error?.code
// Error?.message
}
To publish and subscribe to location data, you just have to use the methods below, the tracking methods for both self tracking and pub/sub tracking remain the same.
Location data will be published and sent to the Roam servers for further processing. The data will be saved on our database servers.
let metaData:Dictionary<String,Any> = ["key":"value"]
let locationData = RoamPublish()
locationData.meta_data = metaData
Roam.publishSave(locationData)
To stop publishing the location data to other clients.
Roam.stopPublishing();
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.
Roam.subscribe(TYPE, "ROAM-USER-ID");
Roam.unSubscribe(TYPE, "ROAM-USER-ID");
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 location updates. |
You can pass an empty
user_id
which is an optional field from v0.0.16 to unsubscribe from all users.Listeners are needed to consume the location or event data from the SDK.
In order to enable listeners, the following must be ensured.
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 toggle the location and event listener to
true
. 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(Events: true, Locations: true) {(RoamUser, Error) in
// Access Roam user data below
// RoamUser?.userId
// RoamUser?.description
// RoamUser?.locationListener
// RoamUser?.eventsListener
// RoamUser?.locationEvents
// RoamUser?.geofenceEvents
// RoamUser?.tripsEvents
// RoamUser?.nearbyEvents
// Access error code & message below
// Error?.code
// Error?.message
}
You can also get the current status of listeners with this method.
Roam.getListenerStatus() {(RoamUser, Error) in
// Access Roam user data below
// RoamUser?.userId
// RoamUser?.description
// RoamUser?.locationListener
// RoamUser?.eventsListener
// RoamUser?.locationEvents
// RoamUser?.geofenceEvents
// RoamUser?.tripsEvents
// RoamUser?.nearbyEvents
// Access error code & message below
// Error?.code
// Error?.message
}
To listen to events on the server-side, you should enable events for the user using the below method.
Roam.toggleEvents(Geofence: true, Location: true, Trips: true, MovingGeofence: true { (RoamUser, Error) in
// Access Roam user data below
// RoamUser?.userId
// RoamUser?.description
// RoamUser?.locationListener
// RoamUser?.eventsListener
// RoamUser?.locationEvents
// RoamUser?.geofenceEvents
// RoamUser?.tripsEvents
// RoamUser?.nearbyEvents
// Access error code & message below
// Error?.code
// Error?.message
}
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, 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.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 didReceiveEvents(_ events: RoamEvents) {
// Do something with user events
}
func didReceiveUserLocation(_ location: RoamLocationReceived) {
// Do something with other users' subscribed location
}
func didReceiveTripStatus(_ tripStatus: [RoamTripStatusListener]) {
//do something with trip status data
}
}
Last modified 7mo ago