{"_id":"59d5792f73506c00109c884d","project":"568bdc1483d2061900d86cdc","version":{"_id":"59a72290d61777001b6c42c3","project":"568bdc1483d2061900d86cdc","__v":19,"createdAt":"2017-08-30T20:39:44.453Z","releaseDate":"2017-08-30T20:39:44.453Z","categories":["59a7236e3fe4d90025117c10","59a72eb6cb0db3001b84cfe2","59a734eb757d030019b85af8","59c0243b1b2d07001a9d2b76","59c035e42126e10028effb12","59c06c40df5b3c0010584a13","59c1a5852cabe5002641a3e7","59c2fb00b2b45c0010b7a3d7","59c32ceb9aea850010ac4130","59c32e6e190c90003cb0d12f","59c33affb2b45c0010b7aa23","59c7dfa457bd8200105444dc","59c7e975c50cf30010d712a0","59cffdef0cd4dd0010294d54","59d0622ca91a810032c8f60c","59d06733c1aec60026253065","59d174d44ac471001a07b123","59d5a5e323e6e800103defb2","59ecf1d8ed507c001c52b255"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"0.0.0","version":"0"},"category":{"_id":"59d174d44ac471001a07b123","project":"568bdc1483d2061900d86cdc","version":"59a72290d61777001b6c42c3","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-10-01T23:05:56.293Z","from_sync":false,"order":5,"slug":"real-time-monitoring","title":"Real Time Monitoring"},"user":"58cc41f21751ce2f003be3b7","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-10-05T00:13:35.033Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"# Overview\n\nThe 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.\n\nThe WebSocket SDK source ccode an be found on [GitHub](https://github.com/droplit/droplit-websocket-sdk).\n\nThe SDK can subscribe to devices or environments.\n\nDo not use this SDK for servers. To get notifications from servers, use webhooks, which are described in the platform overview.\n\n# Installation\n\nThe WebSocket SDK can be installed using Bower, NPM. It can also be used with Browserify, if desired.\n\n## Bower\n\nInstall the SDK with the following command.\n\n```\nbower install droplit-websocket-sdk --save\n```\n\nAfter 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.\n\n```\nvar droplitSocket = new DroplitWebSocketClient.DroplitClient();\n```\n\n## NPM\n\nInstall the SDK with the following command.\n\n```\nnpm install droplit-socket-sdk --save\n```\n\nTo use the SDK, reference the package `droplit-socket-sdk`.\n\n```\nvar droplitSDK = require('droplit-socket-sdk');\nvar droplitSocket = new droplitSDK.DroplitClient();\n```\n\n## Browserify\n\nBrowserify must be installed globally to ensure it works with the SDK.\n\n```\nnpm install -g browserify\nbrowserify index.js > bin/droplit-websocket-sdk.js --standalone DroplitWebSocketClient\n```\n\n# SDK Events\n\nThe 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.\n\n```\ninterface payload {\n    type: string,\n    ecosystemId: string,\n    environmentId: string,\n    deviceId: string,\n    service: string,\n    index: string,\n    member: string,\n    value?: any\n}\n```\n\nThe “type” property can be any of the following values, depending on what action caused the event.\n\n- Call: A method was called on the resource.\n- Changed: Any resource property has been changed.\n- Error: A device error was thrown.\n- Event: A service property event was emitted.\n- Get: A resource property was refreshed.\n- Info: Resource information was received.\n- Set: A resource property was explicity set.\n\n## event\n\nThis event type is received when the subscribed resource emits the event payload data specified above.\n\n```\ndroplitSocket.on('event', function (data) {\n    console.log(\"event\", data);\n});\n```\n\n## authenticateRequest\n\nOnce 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.\n\nUse the `authenticate()` method to supply the authorization token.\n\nIf the socket must be re-authenticated at a later point in time, it is safe to use 'authenticateRequest` and 'authenticate()' in this way again.\n\n```\ndroplitSocket.on('authenticateRequest', function () {\n    // Call authenticate()\n});\n```\n\n## authenticated\n\nOnce this event is received, the SDK may subscribe to resources.\n\n```\ndroplitSocket.on('authenticated', function () {\n    // Subscribe to resources    \n});\n```\n\n## connected\n\nThis event occurs when the web socket connection is established.\n\n```\ndroplitSocket.on('connected', function () {\n    console.log('Connection established.');\n});\n```\n\n## closed\n\nThis event occurs when the web socket connection is closed. It can happen from explicitly closing the connection, or the connection being lost.\n\n```\ndroplitSocket.on('closed', function () {\n    console.log('Connection closed.');\n});\n```\n\n## socketInfo\n\nThis event occurs when the web socket connection is upgraded.\n\n```\ndroplitSocket.on('socketInfo', function (info) {\n    console.log(info);\n});\n```\n\n## socketError\n\nThis event occurs when the web socket connection encounters an error.\n\n```\ndroplitSocket.on('socketError', function (error) {\n    console.log(error);\n});\n```\n\n# SDK Methods\n\n## authenticate(authorizationToken: string)\n\nThis method should be called whenever the `authenticateRequest` event is received. \n\n```\ndroplitSocket.authenticate('+gbSKJBQ7BvJ0DfAyBZqNuAkyFvF0nME7mWUzj+JPfvDWHr4fNhGow1WRJnPhyOOzCnHUFzLaJgcLMj/PI0fpYG7xn3snwvHB+JRvhAujLRbDyPpz0IRYM01oGKfQ+Kc');\n```\n\nThis example calls a custom method `retreiveAuthToken` to get the user authorization from the application local storage.\n\n```\ndroplitSocket.on('authenticateRequest', function () {\n    droplitSocket.authenticate(retreiveAuthToken());\n});\n```\n\n## subscribe(resourceId: string)\n\nThis method allows an application to receive notifications about a provided resource. The web socket must be properly authenticated for this method to work.\n\n```\ndroplitSocket.subscribe('E5847573f80ffaa4540a761ff');\n```\n\n## unsubscribe(resourceId: string)\n\nThis method allows an application to stop receiving notifications about a provided resource. The web socket must be properly authenticated for this method to work.\n\n```\ndroplitSocket.unsubscribe('E5847573f80ffaa4540a761ff');\n```\n\n## reopen()\n\nThis 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.\n\n```\ndroplitSocket.reopen();\n```\n\n## close()\n\nThis 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.\n\n```\ndroplitSocket.close();\n```","excerpt":"","slug":"web-socket-sdk","type":"basic","title":"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 ccode an be found on [GitHub](https://github.com/droplit/droplit-websocket-sdk). 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. # 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-socket-sdk --save ``` To use the SDK, reference the package `droplit-socket-sdk`. ``` var droplitSDK = require('droplit-socket-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. - 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. ## 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(); ```