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:
<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>
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 <a href="/docs/api-clients/observable-rooms">observable rooms.</a> |
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.
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));