{"_id":"59d5792f73506c00109c884d","project":"568bdc1483d2061900d86cdc","version":{"_id":"59a72290d61777001b6c42c3","project":"568bdc1483d2061900d86cdc","__v":29,"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","59f76fef8581dc0010593e6f","5a0c003680a35b0012c35db0","5a8358722e78660075e45f42","5a846645b5ec3a001203517e","5b258091bc7a6700033b9cb5","5b26e48e024807000315a740","5b44edff3306680003663f5c","5b468abd3d4a9e0003789111","5b468d8f3dcb6a0003c6e374","5b47b0b93d4a9e000378a33a"],"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":6,"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 code 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\nIt 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.\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-websocket-sdk --save\n```\n\nTo use the SDK, reference the package `droplit-websocket-sdk`.\n\n```\nvar droplitSDK = require('droplit-websocket-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## Service Events\n\nService events spawn websockets when a device's service properties are modified or its service methods are called.\n\nTypes of service events include:\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## Data Events\n\nData events spawn websockets when a device itself is modified.\n\nTypes of data events include:\n- __Created__: A device has been created.\n- __Updated__: A device's data has been updated.\n- __Deleted__: A device has been deleted.\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 code 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. 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(); ```