JavaScript API

To include the Scaledrone client library in your website, add the Scaledrone JavaScript library script tag to the <head> section of your HTML file.

You can choose between two JS library versions:

Full library
WebSockets-only library
<script src='https://cdn.scaledrone.com/scaledrone.min.js' type='text/javascript'></script>
<script src='https://cdn.scaledrone.com/scaledrone-lite.min.js' type='text/javascript'></script>
Do not host this file yourself.

Connecting

To connect to a channel you need to first create it in the admin panel of Scaledrone's website. One instance of Scaledrone establishes a single connection.

const drone = new Scaledrone('CHANNEL_ID_FROM_DASHBOARD');

Events

open event

A connection has been opened. The error argument indicates a problem with the connection.

drone.on('open', error => {
  // Connection has been opened if no error
});

error event

An error has occurred with the connection.

drone.on('error', error => {
  // An error has occurred with the connection
});

close event

Connection to Scaledrone has been closed. After this event, Scaledrone will not try to automatically reconnect.

drone.on('close', event => {
  // Connection has been closed
});

disconnect event

User has disconnected and Scaledrone is trying to reconnect.

drone.on('disconnect', () => {
  // User has disconnected, Scaledrone will try to reconnect soon
});

reconnect event

User has successfully reconnected after disconnecting.

drone.on('reconnect', () => {
  // User has been reconnected
});

Listening to messages

All messages move within rooms. To listen to messages, you need to subscribe to a specific room.
Users can connect to multiple rooms (this does not create extra connections).

// Subscribe after the 'open' or 'authenticate' event from the Scaledrone instance
const room = drone.subscribe('room_name');

room.on('open', error => {
  if (error) {
    return console.error(error);
  }
  // Connected to room
});

room.on('data', data => {
  // Received data from room
});

Sending messages

All users subscribed to the room will receive the message (also the publishing user, if it's subscribed). You don't have to be subscribed to a room when publishing to it.

The message can be anything that can be stringified as JSON and then parsed (for example a Number, String or an Object).

drone.publish({
  room: 'room_name',
  message: {hello: 'world'}
});

Closing the connection

Closes the connection to Scaledrone.

drone.close();

Unsubscribing from a room

Stops listening to messages from the room.

room.unsubscribe();

Who's online functionality

To keep track of users that are connected to a room see the observable rooms documentation.

Authentication

Client authentication is an optional step and can only be used when you have set up a JWT server. Read more about this from the authentication documentation

Full example

Make sure you replace the CHANNEL_ID string with your Scaledrone channel's ID from the dashboard.

Subscribe to messages
Subscribe and publishing messages
const drone = new Scaledrone('CHANNEL_ID');
drone.on('error', error => console.error(error));

const room = drone.subscribe('my-room');
room.on('data', data => console.log('Received data object:', data));
const drone = new Scaledrone('CHANNEL_ID');

drone.on('open', error => {
  if (error) {
    return console.error(error);
  }
  drone.publish({
    room: 'my-room',
    message: {message: 'Hello world!', score: 42}
  });
});

const room = drone.subscribe('my-room');
room.on('open', error => {
  if (error) {
    console.error(error);
  } else {
    console.log('Connected to room');
  }
});
room.on('data', data => console.log('Received data:', data));

drone.on('error', error => console.error(error));