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.