@kandy-io/uc-sdk-3.x

--- layout: page categories: quickstarts-javascript title: User Connect permalink: /quickstarts/javascript/uc/User%20Connect --- # Connecting and Disconnecting In this quickstart we will cover how to connect and disconnect to the Kandy Platform using Kandy.js. We will provide snippets of code below, which together will form a working demo application. The first step with Kandy.js is always to initialize it. You will need to know the server information for the Kandy platform that you are using for initialization. Depending on your platform, the only required configuration is the server address, as the others have generic defaults. ```javascript import { create } from kandy const kandy = create({ // Required: Server connection configs. authentication: { subscription: { server: ..., ... }, websocket: { server: ..., ... } } }) ``` To learn more about initializing Kandy, see our [Configuration Quickstart](Configurations). **This example does not provide data for `authentication` but it is required.** Since we're going to be making a working demo, we also need some HTML. The HTML for this demo is quite simple. ```html <div id="auth-state">Connected: false</div> <input type="submit" value="Login" onclick="login();" /> <input type="submit" value="Logout" onclick="logout();" /> <div id="messages"></div> ``` What we have is a simple div containing the connected state of our app, two buttons, and an element for logging messages to. ## Step 1: Connecting To connect using Kandy, you will need two things: 1. A username. This is the full username of a user on your domain. (Example: your-user@your-domain.kandy.io) 1. A password. Don't worry, its safe with us. With these three things, you can call the connect function on Kandy. ```javascript function login () { kandy.connect({ username: username, password: password }) } ``` ## Step 2: Connection Events The `kandy.connect()` function does not return a value. Instead, Kandy.js uses events to tell you when something has changed. You can find a list of the authentication events in the API documentation. To subscribe to these events, you use `kandy.on()`. Here is the example for our demo app: ```javascript kandy.on('auth:change', function () { let isConnected = kandy.getConnection().isConnected document.getElementById('auth-state').innerHTML = 'Connected: ' + isConnected log('Connection state changed.') }) ``` If something goes wrong when we try to connect (invalid credentials maybe), we want to know. Kandy.js has an `auth:error` event to support this. ```javascript // Listen for authentication errors. kandy.on('auth:error', function (params) { log('Connect error: ' + params.error.message + ' (' + params.error.code + ')') }) ``` In the above piece of code we subscribe an anonymous function to the `auth:change` event. Now, whenever Kandy fires off an `auth:change` event, that function will be called. Inside this function we call `kandy.getConnection()`. This function returns an object that looks like so: ```javascript { isConnected: true, isPending: false, error: undefined } ``` To learn more about the response from this API checkout the API documentation for `getConnection`. ## Step 3: Disconnecting To disconnect, you simply call disconnect. ```javascript function logout () { kandy.disconnect() } ``` Calling this function will trigger a change in the connection state, which in turn will trigger any listeners to the `auth:change` event. You can therefore use your `auth:change` listener to detect if the disconnect was successful. In situations where the application is going to be used by another user and you want to protect their data privacy, the destroy function will tear down the SDK and render it unusable. Afterwards the SDK can be created again so no data is passed between users who shouldn't have access. ```javascript function logout () { kandy.on('auth:change', params => { const connection = kandy.getConnection() if (connection.isConnected === false && connection.isPending === false) { // If user is not connected and an operation is not pending, then the user disconnected. kandy.destroy() } }) kandy.disconnect() } ``` ### Live Demo Want to play around with this example for yourself? Feel free to edit this code on Codepen. <form action="https://codepen.io/pen/define" method="POST" target="_blank" class="codepen-form"><input type="hidden" name="data" value=' {"js":"/**\n * Kandy.io Authentication Demo\n */\n\nconst { create } = Kandy\nconst kandy = create({\n // Required: Server connection configs.\n authentication: {\n subscription: {\n server: ...,\n ...\n },\n websocket: {\n server: ...,\n ...\n }\n }\n})\n\nvar username = 'UsernameHere'\nvar password = 'PasswordHere'\n\nfunction login () {\n kandy.connect({\n username: username,\n password: password\n })\n}\n\nkandy.on('auth:change', function () {\n let isConnected = kandy.getConnection().isConnected\n document.getElementById('auth-state').innerHTML = 'Connected: ' + isConnected\n log('Connection state changed.')\n})\n\n// Listen for authentication errors.\nkandy.on('auth:error', function (params) {\n log('Connect error: ' + params.error.message + ' (' + params.error.code + ')')\n})\n\nfunction logout () {\n kandy.disconnect()\n}\n\nfunction logout () {\n kandy.on('auth:change', params => {\n const connection = kandy.getConnection()\n if (connection.isConnected === false && connection.isPending === false) {\n // If user is not connected and an operation is not pending, then the user disconnected.\n kandy.destroy()\n }\n })\n kandy.disconnect()\n}\n\n// Utility function for appending messages to the message div.\nfunction log (message) {\n document.getElementById('messages').innerHTML += '<div>' + message + '</div>'\n}\n\n","html":"<div id=\"auth-state\">Connected: false</div>\n\n<input type=\"submit\" value=\"Login\" onclick=\"login();\" />\n<input type=\"submit\" value=\"Logout\" onclick=\"logout();\" />\n\n<div id=\"messages\"></div>\n\n","css":"","title":"Kandy.io Authentication Demo","editors":"101","js_external":"https://unpkg.com/@kandy-io/uc-sdk-3.x@3.28.0/dist/kandy.js"} '><input type="image" src="./TryItOn-CodePen.png"></form>