Javascript Library

Search…
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
Note: Before you get started signup to our dashboard to get your Publishable Keys.
Installation:
Via NPM
You can install our package using npm.
Via CDN
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.
Usage
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 parameters
groupSubscription(greoupID) - takes in group ID as parameter
userSubscription(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)
})
Methods
Initialize
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("")
Setting up a callback function
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)
Subscription
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. 
Disconnect
To disconnect from our server, call the disconnect()method on the client.
Library Integration Examples
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.
GitHub - roam-ai/roam-js: JavaScript Pub/Sub Library; JS library to subscribe to realtime location updates from Roam.ai's location SDKs.
GitHub
roam.js
Need Help?
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 5mo ago
Export as PDF
Copy link
On this page
Installation:
Via NPM
Via CDN
Usage
Methods
Initialize
Setting up a callback function
Subscription
Disconnect
Library Integration Examples
Need Help?