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');

Scaledrone 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('message', message => {
  // Received message from room
});

Room Events

message event

Received a message that was sent to the room. The message object structure looks like this:

Property Datatype Example value Always exists Comment
data object, string, number "Hello" The actual data that was sent to the room
id string "oNx1aglcnb" Unique ID of the message
timestamp integer 1547049305 Unix timestamp
clientId string "pfH6Al1v0i" ID of the socket client who sent the message. Is undefined when message was sent using a REST API.
member object The member who sent the message. Exists when using observable rooms.
room.on('message', message => {
  const {data, id, timestamp, clientId, member} = message;
});

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('message', message => console.log('Received message:', message));
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('message', message => console.log('Received message:', message));

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