Droplit.io Portal
API Reference

WebSocket SDK

Overview

The Droplit WebSocket SDK provides NodeJS or a web application with real-time device state change notifications. Application UIs can use this to dynamically update when the states of devices change.

The WebSocket SDK source code an be found on GitHub.

The SDK can subscribe to devices or environments.

Do not use this SDK for servers. To get notifications from servers, use webhooks, which are described in the platform overview.

It is possible that several events will be captured by the websocket simultaneously. In the case of such an occurrence, each event will have its own entry in the "items" array of each transaction.

Installation

The WebSocket SDK can be installed using Bower, NPM. It can also be used with Browserify, if desired.

Bower

Install the SDK with the following command.

bower install droplit-websocket-sdk --save

After referencing droplit-socket-sdk.js in html, DroplitWebSocketClient is declared in the global scope, and a new instance of a Droplit socket can be created.

var droplitSocket = new DroplitWebSocketClient.DroplitClient();

NPM

Install the SDK with the following command.

npm install droplit-websocket-sdk --save

To use the SDK, reference the package droplit-websocket-sdk.

var droplitSDK = require('droplit-websocket-sdk');
var droplitSocket = new droplitSDK.DroplitClient();

Browserify

Browserify must be installed globally to ensure it works with the SDK.

npm install -g browserify
browserify index.js > bin/droplit-websocket-sdk.js --standalone DroplitWebSocketClient

SDK Events

The droplitSocket instance emits events when something changes in a resource that it is monitoring. Events contain a variety of information about the resource that spawned them, as shown.

interface payload {
    type: string,
    ecosystemId: string,
    environmentId: string,
    deviceId: string,
    service: string,
    index: string,
    member: string,
    value?: any
}

The “type” property can be any of the following values, depending on what action caused the event.

Service Events

Service events spawn websockets when a device's service properties are modified or its service methods are called.

Types of service events include:

  • Call: A method was called on the resource.
  • Changed: Any resource property has been changed.
  • Error: A device error was thrown.
  • Event: A service property event was emitted.
  • Get: A resource property was refreshed.
  • Info: Resource information was received.
  • Set: A resource property was explicity set.

Data Events

Data events spawn websockets when a device itself is modified.

Types of data events include:

  • Created: A device has been created.
  • Updated: A device's data has been updated.
  • Deleted: A device has been deleted.

event

This event type is received when the subscribed resource emits the event payload data specified above.

droplitSocket.on('event', function (data) {
    console.log("event", data);
});

authenticateRequest

Once a socket connection is opened, it must then be authenticated. When an authenticateRequest event is receieved, the user authorization token must be supplied. Resources cannot be accessed until this happens.

Use the authenticate() method to supply the authorization token.

If the socket must be re-authenticated at a later point in time, it is safe to use 'authenticateRequest` and 'authenticate()' in this way again.

droplitSocket.on('authenticateRequest', function () {
    // Call authenticate()
});

authenticated

Once this event is received, the SDK may subscribe to resources.

droplitSocket.on('authenticated', function () {
    // Subscribe to resources    
});

connected

This event occurs when the web socket connection is established.

droplitSocket.on('connected', function () {
    console.log('Connection established.');
});

closed

This event occurs when the web socket connection is closed. It can happen from explicitly closing the connection, or the connection being lost.

droplitSocket.on('closed', function () {
    console.log('Connection closed.');
});

socketInfo

This event occurs when the web socket connection is upgraded.

droplitSocket.on('socketInfo', function (info) {
    console.log(info);
});

socketError

This event occurs when the web socket connection encounters an error.

droplitSocket.on('socketError', function (error) {
    console.log(error);
});

SDK Methods

authenticate(authorizationToken: string)

This method should be called whenever the authenticateRequest event is received. 

droplitSocket.authenticate('+gbSKJBQ7BvJ0DfAyBZqNuAkyFvF0nME7mWUzj+JPfvDWHr4fNhGow1WRJnPhyOOzCnHUFzLaJgcLMj/PI0fpYG7xn3snwvHB+JRvhAujLRbDyPpz0IRYM01oGKfQ+Kc');

This example calls a custom method retreiveAuthToken to get the user authorization from the application local storage.

droplitSocket.on('authenticateRequest', function () {
    droplitSocket.authenticate(retreiveAuthToken());
});

subscribe(resourceId: string)

This method allows an application to receive notifications about a provided resource. The web socket must be properly authenticated for this method to work.

droplitSocket.subscribe('E5847573f80ffaa4540a761ff');

unsubscribe(resourceId: string)

This method allows an application to stop receiving notifications about a provided resource. The web socket must be properly authenticated for this method to work.

droplitSocket.unsubscribe('E5847573f80ffaa4540a761ff');

reopen()

This method reopens the socket connection by creating a new DroplitClient instance. This method only works if the socket was explicitly closed at some time prior to calling it.

droplitSocket.reopen();

close()

This method closes the socket connection. Any subscriptions associated with the closed socket will be destroyed, and the user will be notified of any subscriptions destroyed in that way.

droplitSocket.close();