Javascript Library
The Javascript library for Roam Location Subscription is used to subscribe to user locations at a project level. It can also be used to subscribe to the locations of a single user.
roam-js supports subscription to the following location data:
- Specific user
- All users of a group
- All users of project
You can install our package using npm.
roam-js bundle is available through http://unpkg.com, specifically at https://unpkg.com/roam-js/dist/roam.min.js. See http://unpkg.com for the full documentation on version ranges.
You can think of this library as a wrapper around our REST API which needs your Publishable Key for authorization and it works at the project level. It is fairly simple to use:
Initialize()the package with the publishable key. This will return an instance of our client.- Define your custom callback function.
client.setCallback(fn) - Create an instance of a subscription. You can create a subscription for a project, user or group of users using the following methods on the client:
projectSubscription()takes no parametersgroupSubscription(greoupID)- takes in group ID as parameteruserSubscription(userID)- takes in a single user ID or an array of user ids as parameter
- Use
subscribe()method on the created subscription to start receiving realtime location data - To stop receiving data, call the unsubscribe method.
- To
disconnect()call disconnect method on client. Please find the example usage below:
var roam = require("roam-js")
const pk = process.env.roam_pk;
roam.Initialize(pk)
.then((client)=>{
client.setCallback(function(message){console.log(message)})
client.projectSubscription()
.then((subscription)=>{
subscription.subscribe()
.then((msg)=>{
console.log(msg)
subscription.unsubscribe()
.then((msg)=>{
console.log(msg)
client.disconnect().then((msg)=>{
console.log(msg)
})
})
.catch((err)=>{
throw(err)
})
}
)
})
.catch((err)=>{
throw(err)
})
})
.catch((err)=>{
throw(err)
})
The first order of the process is the initialization of the library. The
Initialize() function takes in the publishable key as a parameter. You can get the publishable key from our dashboard once you create a project. Initialize returns a promise of our client.client = await roam.Initialize("")
Once initialized, we recommend setting up a callback function. This callback function will be called once you receive any location data from our backend.
var callback = function(data){
console.log(data)
}
client.setCallback(callback)
As mentioned above, roam-js supports 3 types of subscriptions:
- project subscription
- user subscription
- group subscription
Project Subscription
To create a subscription that allows you to subscribe to location data of all users within the project, you can use
projectSubscription() method of client. It does not take in any parameter.subscription = await client.projectSubscription()
Group Subscription
To create a subscription that allows you to subscribe to the location data of all users within the group, you can use the
groupSubscription(groupID) method of the client. It takes the group ID as a parameter.subscription = await client.groupSubscription('')
User Subscription
To create a subscription that allows you to subscribe to the location data of a single user or multiple users, you can use the
userSubscription(groupID) method of client. It takes the user ID as a parameter.subscription = await client.groupSubscription('user_1')
To subscribe to multiple users, pass the userIDs in an array as a parameter.
subscription = await client.groupSubscription(['user_1','user_2'])
Subscribe to a subscription
All of the above methods will give you a subscription promise. You can subscribe to the subscription by using the following:
subscription.subscribe()
This will either return a promise with a success message if you've subscribed to the subscription or will throw an error.
Unsubscribe from a subscription
To stop getting location updates from a subscription, you can use the
unsubscribe() method.subscription.unsubscribe()
This will either return a promise with a success message if you've unsubscribed from the subscription or will throw an error.
To disconnect from our server, call the
disconnect()method on the client.See example codes in
examples/. To run the example, clone this repository, add your sdk key as an environment variable pk and run the app.
If you have any problems or issues regarding our SDK, feel free to create a github issue or submit a request on Roam Help.
Last modified 4mo ago