Pub/Sub Locations (iOS)

Explore how to publish and subscribe locations for iOS.

Creating Users

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

// 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)

Objective-C

// update user with meta-data and description
// Declare meta-data as dictionary
// Description as string
[Roam updateUser:@"userDescription" :@"metadata"];

Get User

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
        }

Publish Messages

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){ status, error in
                
}

To stop publishing the location data to other clients.

Roam.stopPublishing(){ status, error in

};

Subscribe to 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

Roam.subscribe(TYPE, "ROAM-USER-ID"){ status, userId, error in

};

UnSubscribe

Roam.unSubscribe(TYPE, "ROAM-USER-ID"){ status, userId, error in
                
};

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 emptyuser_id which is an optional field from v0.0.16 to unsubscribe from all users.

Location Listener

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
        }

Toggle Events

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.

Location Listener

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
    }
}