Roam.ai Docs
HomeContactDashboard
  • Introduction
  • Getting Started
    • Key Concepts
  • Frameworks
  • Android
    • Quickstart (Android)
    • Pub/Sub Locations (Android)
    • SDK Methods (Android)
      • SDK Configuration (Android)
      • Get Current Location (Android)
      • Update Current Location (Android)
      • Update Location When Stationary (Android)
      • Trip v1 SDK Methods (Android)
      • Trip v2 SDK Methods (Android)
        • Create Trip (Android)
        • Update Trip (Android)
        • Start Quick Trip (Android)
        • Start Trip (Android)
        • End Trip (Android)
        • Pause Trip (Android)
        • Resume Trip (Android)
        • Sync Trip (Android)
        • Get Trip (Android)
        • Get Active Trips (Android)
        • Get Trip Summary (Android)
        • Subscribe to Trip (Android)
        • Delete Trip (Android)
    • Utility Methods (Android)
    • Troubleshooting (Android)
    • Changelog (Android)
  • iOS
    • Quickstart (iOS)
    • Pub/Sub Locations (iOS)
    • SDK Methods (iOS)
      • SDK Configuration (iOS)
      • Get Current Location (iOS)
      • Update Current Location (iOS)
      • Update Location When Stationary (iOS)
      • Trips v1 SDK Methods (iOS)
      • Trips v2 SDK Methods (iOS)
        • Create Trip (iOS)
        • Update Trip (iOS)
        • Start Quick Trip (iOS)
        • Start Trip (iOS)
        • End Trip (iOS)
        • Pause Trip (iOS)
        • Resume Trip (iOS)
        • Sync Trip (iOS)
        • Get Trip (iOS)
        • Get Active Trips (iOS)
        • Get Trip Summary (iOS)
        • Subscribe Trip (iOS)
        • Delete Trip (iOS)
    • Utility Methods (iOS)
    • Troubleshooting (iOS)
    • Changelog (iOS)
  • React Native
  • Flutter
  • PRODUCTS
  • Tracking (BETA)
  • Geofencing
  • Trips
  • APIs
    • Authorization
    • Users API
      • Create User API
      • Get User API
      • Update User API
    • Locations API
      • Get Locations API
      • Get Stop Locations API
    • Insights API
      • Get User POIs API
      • Get User Home Location API
      • Get User Work Location API
    • Trips v1 API
      • Create Trip API v1
      • Get Trip API
      • Update Trip API v1
      • Delete Trip API v1
      • Trip Summary API
      • Export Trip Summary as GPX
    • Trips v2 API
      • Create Trip API
      • Get Single Trip API
      • Get Multiple Trips API
      • Update Trip API
      • Control Trip API
        • Start Trip API
        • Pause Trip API
        • Resume Trip API
        • End Trip API
      • Get Trip Summary API
      • Export Trip API
      • Delete Trip API
    • Geofencing API
      • CREATE Geofence API
      • GET Geofence API
      • UPDATE Geofence API
      • DELETE Geofence API
    • Events API
      • Get Events
      • Trip Events
    • Nearby API
      • Get Nearby User API
      • Get Nearby Geofence API
    • Moving Geofence API
      • Create Moving-Geofence API
      • Update Moving-Geofence API
      • GET Moving-Geofence API
      • Delete Moving-Geofence API
    • User Groups API
      • Create Group API
      • Get User Group by ID
      • Get User Group List
      • Add Users to Group API
      • Update Group API
      • Find Nearby Users from Group
    • Query with Metadata
  • WEBHOOK
    • Webhook
    • Slack Integration
  • LIBRARIES
    • Javascript Library
    • Go Library
    • Python Library
Powered by GitBook
On this page
  • Installation:
  • Usage
  • Methods
  • Need Help?

Was this helpful?

Export as PDF
  1. LIBRARIES

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.

PreviousSlack IntegrationNextGo Library

Last updated 2 years ago

Was this helpful?

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 to get your Publishable Keys.

Installation:

Via NPM

You can install our package using npm.

Via CDN

roam-js bundle is available through , specifically at . See 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.

Need Help?

If you have any problems or issues regarding our SDK, feel free to create a github issue or submit a request on .

signup to our dashboard
http://unpkg.com
https://unpkg.com/roam-js/dist/roam.min.js
http://unpkg.com
Roam Help
LogoGitHub - 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