Tutorial: Intro to kaazing.io

This tutorial walks you through the steps to use kaazing.io for the first time

In the tutorial you will use a sandbox Kafka broker that has been supplied for you. If you have your own Kafka broker that you’d like to use, the Using Your Own Kafka section towards the end of the tutorial has steps for that.

Register for kaazing.io

You start by registering at https://console.kaazing.io

It’s free, and you don’t have to enter any credit cards to get started.

Note

When signing up, pick a username that is URL-friendly as it will be used in the kaazing.io Admin Console URLs. This is similar to way GitHub puts your username in its URLs.

Sign up

kaazing.io Administration Console

Once you’ve signed up, you will have access to the kaazing.io Administration Console. That is where you configure everything you need for your client applications to be able to receive streaming data from Kafka.

Creating a New App

Whenever you log in kaazing.io Administration Console, you’ll see your list of apps. An app, in the context of kaazing.io, defines the configuration mapping between your backend Kafka broker and your client application.

Initially your app list will be empty, so you’ll be prompted to press the Add a New App button. Go ahead and press the button to get started:

Empty app list

Kafka Reachability

In the Add a new app dialog, you are first asked about how to connect to your Kafka broker:

Creating a new app - Kafka reachability choice

In this part of the tutorial you’ll use a sandbox Kafka made available to you by kaazing.io, rather than your own. Later on in the tutorial, the Using Your Own Kafka section covers how to connect to your broker.

For now, click Select in the first box:

Creating a new app - Sandbox

You won’t have to enter any further details when using the sandbox Kafka. When your configuration has been created and the connection test is successful, go ahead and press the Done button.

The App List

You will be returned to the main screen showing your list of kaazing.io apps. You’ll see the new app you just created called kaazing-sandbox.

Status

Notice that the status on the right says it’s updating:

App status - Updating

Whenever you add or modify an app configuration, the change needs to be provisioned in kaazing.io. You’ll know it has taken effect once the status is live:

App status - Updating

App Configuration

An app configuration defines:

  1. A nickname to help you remember what this app is for
  2. The domain name used in the streaming URLs
  3. The connection details and status of the Kafka broker cluster
  4. The Server-Sent Events (SSE) endpoint URLs that your client applications will use to stream data
  5. The topics used by the endpoint URLs

Components of a kaazing.io app

Viewing the Data

Once your app configuration is ready, you can start looking at the data and verifying it’s what you expect.

There are various ways you can see the data, two of them are described here in the tutorial.

Live Data Preview in the Console

Click the Show Live Data icon on the right-hand side of the /topic/sandbox.stocks row:

Show Live Data icon

This will show live messages from the sandbox.stocks topic as they are published into Kafka. Behind the scenes, we are running a publisher that is sending messages into the sandbox Kafka so that you have some test messages here:

Live Data preview

Note

To hide the live data preview, click the Show Live Data icon again.

Code Template for Javascript

Click the Show Code Template icon:

Javascript Template Code

This will show you a HTML and Javascript code template that streams the data into a HTML5 application.

Press the download button and use a browser to open the HTML file that was saved. You can click on the download directly if your browser supports it – like the screenshot below – otherwise open it yourself from wherever you saved it.

Javascript Template Data

Alternatively, you can copy the text with the copy-to-clipboard button and save it to a .html file, which you can then open in a browser:

Javascript Template Data

Whichever method you chose, once you open the template application in a browser, you will see the messages displayed on the screen:

Javascript Template Data

You can view the source to see the entire application.

This template shows how you can easily stream data into your own application. We’ll go into more detail on that later in the Creating Your Own Application section.

Understanding the App Configuration

Close the live preview:

Close live preview

You should now see your configuration again. Right now you only have one app configuration, called kaazing-sandbox.

App Domains

An app configuration is a grouping of Server-Sent Events (SSE) endpoint URLs. Your client application will connect to those URLs in order to stream data from Kafka. All of the URLs have the same domain address with a different path.

SSE URL components

Notice that all of the URLs above have the same domain address, namely, in this example: 1egnyqax.streaming.kaazing.io. As a convenience, the domain is also shown in the header section of the app configuration.

kaazing.io will dynamically allocate you a domain that you can use. Coming soon, you will able to customize to any domain of your choosing, like streams.myapp.example.com.

If you were to add a new app configuration – perhaps for a different app – it will have a different domain. We’ll do this further down in the tutorial.

Server-Sent Events (SSE) Endpoint URLs

These are your SSE endpoint URLs, each mapped to a specific Kafka topic:

SSE endpoint URLs

You map each stream of data you want clients to receive to different paths. Consider the following two SSE endpoints:

https://1egnyqax.streaming.kaazing.io/topic/sportscores.events
https://1egnyqax.streaming.kaazing.io/topic/sportscores.scores

The first one will stream messages when a sporting event starts or stops, so you know which games are currently being played. The second URL will stream score updates for those events.

As you can see in the list of endpoint URLs, the first URL is mapped to the sandbox.sportscores.events Kafka topic, and the second one is mapped to the sandbox.sportscores.scores Kafka topic.

You can use the kaazing.io admin console to configure any path you like to whichever topics you like. You can delete topic mappings that you don’t want, or you can click the edit icon to modify the path.

Adding a New Topic Mapping

Press the + button to add a new topic mapping:

Add topic mapping

A row will appear. Enter events for the path and select sandbox.sportscores.events for the topic, then press the save (✓) button.

Note

Notice that the status changes to updating because modifications to the app configuration are live and need to be provisioned each time you make a change:

Add topic mapping - Updating

The change will have taken effect once the status is live:

Add topic mapping - Done

You can continue to make other app configuration changes while the status is updating. You don’t need to wait until the status is live before making more changes.

You’ll now have four topic mappings:

New topic mapping added

This shows a couple of things:

  • Kafka topics can be used by more than one topic mapping, since two topic mappings are using the sandbox.sportscores.events topic

  • The path in the topic mapping is independent of the topic name. The first three topic mappings that were automatically created for you simply used the topic name in the path name. However the path can be anything that conforms with valid URL names

Deleting a Topic Mapping

The first two topics in our list will show the same data. This can be seen by expanding the live data view for both of them:

Duplicate topic mappings

Since we don’t need both of them, let’s delete one. The path /events is a better name, and doesn’t expose the name of our topic to the client application, so delete the topic mapping for /topic/sandbox.sportscores.events:

Duplicate topic mappings

Once again, the status will show that the changes are updating, and will be provisioned when the status is live:

Delete topic mapping - Done

Updating a Topic Mapping

Let’s also change the path for the /topic/sandbox.sportscores.scores to /scores. Click the edit button next to the path:

Edit topic mapping button

Change the path to /scores and press the save (✓) button. As usual, the changes will be live once the status is green. Here are the topic mappings now:

Edit topic mapping button - done

That’s the end of the first part of the tutorial

If you would like to drill down further into what the client code is like, then continue with the next section, Creating Your Own Application. If you would like to see how to connect to your own Kafka broker, then jump further down to Using Your Own Kafka.

Creating Your Own Application

Back in the Code Template for Javascript section, you saw how to get a code template for any of your topic mappings.

Starting With the Code Template

Let’s break down that code template so you can see how to easily receive streaming data in your own applications. Firstly, here’s the whole template we looked at, and then we’ll review some of the key lines:

<!DOCTYPE html>
<html lang="en">
  <head>
    <!-- Polyfill for older browsers without native support for the EventSource API. -->
    <script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=EventSource"></script>
  </head>
  <body>
    <div id="payload"></div>
    <script>
      const stream =
          new EventSource('https://1egnyqax.streaming.kaazing.io/topic/sandbox.stocks');
      const handler = event => {
        document.getElementById('payload').innerText = event.data;
      };
      stream.addEventListener('message', handler, false);
    </script>
  </body>
</html>

Supporting Older Browsers

Some older browsers don’t have native support for Server-Sent Events, so include a polyfill:

<html lang="en">
  <head>
    <!-- Polyfill for older browsers without native support for the EventSource API. -->
    <script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=EventSource"></script>
  </head></html>

By adding this one-line polyfill, your application will work in any browser. You don’t need to take any other action or do anything differently in your application. The polyfill only activates if it detects the browser does not support Server-Sent Events; in a modern browser, the polyfill will be ignored.

Creating the EventSource

Server-Sent Events use the standard HTML5 EventSource API. To subscribe to an event stream, create a new EventSource and pass in the URL:

<html lang="en"><body><script>
      const stream =
          new EventSource('https://1egnyqax.streaming.kaazing.io/topic/sandbox.stocks');
</script>
  </body>
</html>

The URL comes directly from the kaazing admin console:

Topic mapping for app

Setting the Message Handler

You won’t receive any data, until you add a handler for the message event:

<html lang="en"><body><script>
      const stream =
          new EventSource('https://1egnyqax.streaming.kaazing.io/topic/sandbox.stocks');
      const handler = event => {
        document.getElementById('payload').innerText = event.data;
      };
      stream.addEventListener('message', handler, false);
    </script>
  </body>
</html>

message is the default EventSource event. (It’s possible to add handlers for other events, too, which we won’t cover here.)

In this case, when the handler receives a message of type message from the event stream, it writes to a <div> on the screen:

<html lang="en"><body>
    <div id="payload"></div>
    <script>
      const stream =
          new EventSource('https://1egnyqax.streaming.kaazing.io/topic/sandbox.stocks');
      const handler = event => {
        document.getElementById('payload').innerText = event.data;
      };
      stream.addEventListener('message', handler, false);
    </script>
  </body>
</html>

In your application, you can decide how you want to handle messages you receive. They can be drawn to the screen, used in a calculation, or used in any other way.

Using Your Own Kafka

If you have a Kafka broker accessible from the internet, then you can configure kaazing.io to stream data from it. If you don’t have a Kafka broker available, don’t worry, you can still read through this section without doing the steps.

Note

Coming soon, we will be adding functionality that lets kaazing.io connect to your Kafka broker if it resides behind a firewall.

To use your own Kafka broker cluster, from the kaazing.io admin console, click the Add a new app button at the top of the screen:

Add new app - Step 1

In the Add a new app dialog, select the Direct option.

Then enter a nickname for this Kafka broker or Kafka broker cluster. The nickname can be whatever you like. It is only used in the kaazing.io admin console to help you remember which app configurations are using which broker.

For the Protocol, choose the setting that matches your Kafka configuration. If it allows plaintext connections, then choose plaintext. If it requires SSL connectivity, then choose ssl.

Next enter the hostname or IP address for your Kafka broker or Kafka broker cluster, and then enter the port. At this point, your screen should look like this:

Add new app - Kafka details

When you’re ready, press the Test Connection button to validate your connection details:

Add new app - Testing the connection

Once the test is successful, press the Done button and you’ll see your new app configuration:

Add new app - Final configuration

You will see the domain you’ve been allocated, as well as a default topic mapping for each topic.

Now you can use this app configuration in your client application, as you’ve already seen earlier in the tutorial.

Using Different Domains

If you completed the previous section, you’ll see that you have two app configurations, like this:

Two apps

Notice that each app configuration has a different domain. The kaazing-sandbox app configuration has a domain of:

1egnyqax.streaming-staging.kaazing.io

while the dev app cofiguration has a domain of:

e4343f8t.streaming-staging.kaazing.io

Generally speaking, you’ll probably want one app for each different Kafka system. For example, you may have one Kafka cluster for DEV and another for PROD. An application can subscribe to whichever of the SSE endpoint URLs it wants to use. For instance, perhaps during the development, your application will use the dev URLs, and in production, the application will use the prod URLs.

Another reason to have different apps with different domains is because you have multiple client applications with different functionality. For example, one application may do sport scores, while another shows stock prices. You can separate their data needs by using different apps with different domains.

Next Steps

Congratulations! You Now that you understand the basics of using kaazing.io, read about more advanced topics, like: