Skip to main content

Client Quickstart (Browser + JS)

In this document we'll set up a client application that will send a message to an echo server using Kanalo. The server can be the one you set up in the Server Quickstart and directed data to in the Config Quickstart, or the default echo that all new Kanalo tenants are configured with.

1. Prerequisites​

The client connects via WebSocket. For all modern browsers since Internet Explorer 10.0, WebSocket is available built-in.

You'll need a host for the HTML app we are creating. You can use any hosting services or tools, or even apps like JSFiddle for it. For a simple local system host you can use http-server from npm to host the created index.html.

2. Updates to the configuration file​

In order to connect to Kanalo this client will need to be whitelisted in the configuration file. You can do so by adding allowedOrigins as an array that contains the url where this application is hosted.

For example, if your application were to be hosted on localhost:8080, you'd add localhost:8080 as shown below. 

version: 1.0.0
... other keys ...
apps:
    echo: 
        ...other keys...
        allowedOrigins:
            - http://localhost:8080/

3. Building the client​

To create our application we'll create a very basic index.html file.

<html>
<head>
<title>Kanalo Echo Example</title>
</head>
<body>
    <div id="output"></div>
    <textarea id="input"></textarea>
    <button id="send">Send</button>
    <script>
        // All code will go here
    </script>
</body>
</html>

Because browsers support the WebSocket protocol, connecting to Kanalo can be done easily by creating the following WebSocket object and giving it your tenant URL. For in-depth detailed documentation of the standard WebSocket object, see MDN's excellent documentation.

const connection = new WebSocket('wss://<tenant>.on.kanalo.dev/<app>?token=<token>');

where <tenant> is your tenant name and <app> is your app name in the configuration file (echo if you are using the default). The default configuration includes a randomly generated static code for authentication, which needs to be sent in the token parameter.

Once a connection is established the WebSocket object will emit a open event. You can add a listener for this using addEventListener method. This accepts a closure that will be called in order to notify your application. 

connection.addEventListener('open', () => {
    console.log("Kanalo has been connected");
});

To send a message you can use connection.send. This would send a hello world to the server:

connection.send("Hello world");

We will put the send statement in a click event listener for the send button, and have it read the text from the input box.

send.addEventListener("click", () => {
    if (!input.value) {
        return;
    }
    connection.send(input.value);
    input.value = "";
});

And to receive messages, listen to the message event:

connection.addEventListener('message', ({ data }) => {
    console.log(`Server said ${data}`);
});

This will send the response to the log, but we will put it on the page instead. Putting the full script together:

const output = document.querySelector('#output');
const input = document.querySelector('#input');
const send = document.querySelector('#send');

send.disabled = true;

const connection = new WebSocket('wss://<tenant>.on.kanalo.dev/<app>');

connection.addEventListener('open', () => {
    console.log("Kanalo has been connected");
    send.disabled = false;
});

connection.addEventListener('message', ({ data }) => {
    const div = document.createElement('div');
    div.textContent = data;
    output.appendChild(div);
});

send.addEventListener("click", () => {
    if (!input.value) {
        return;
    }
    connection.send(input.value);
    input.value = "";
});

This script will go in the script section of the HTML file at the beginning of this section.

4. Using the client​

Once the web page is hosted, either locally or online, you should be able to enter text into the box and see it echoed back if you press the send button.

4.1 Debugging​

If the socket disconnects, we can see what close message was sent by modifying the script to listen to the close event as well:

connection.addEventListener('close', (event) => {
    console.log(`Kanalo has been disconnected. ${event.code}: ${event.reason}`);
    send.disabled = true;
});

If your config was changed to use the server set up in the Server Quickstart, make sure that it is running and accessible.