How to Create an Embedded Dashboard

A dashboard can help you better understand your business, application, process, or any other entity that creates data for analysis. Simply visualizing data is a powerful method to uncover insights, see progress, and motivate yourself–or others–to act.

Creating your dashboard does not need to be complicated. This guide will walk you through a sample project. You will learn how to choose your metrics and collect your data. Then you’ll visualize your data and share it with others. The most complex aspects of your dashboard are covered by Keen IO, with a solid platform for data collection and open source code and layouts for beautiful analytics.

Already sending events to Keen and ready to build a dashboard? Click here!


Dashboard


Choose Your Metrics

You might be tempted to jump into making a dashboard before you think about what data to measure. If you skip this step now, you’ll definitely need to come back. Knowing what you want to track really is the first step because it informs what data you need to collect. Also, since you’ll be communicating these metrics to others with the dashboard, you’re placing significance on them. So, you better make sure they matter.

There is no magic number of metrics to choose and it depends a lot of how you’ll use your dashboard. As a best practice, one is probably too few, and ten is bound to be too many. Your dashboard should give enough information to be valuable without giving too much to be actionable.

By narrowing your focus, you have the flexibility to show each metric in multiple ways. You can view the total for the most recent period, as well as showing the trend, and maybe comparing the metric to another value.

Collect Your Data

Armed with your most important metrics, you’re ready to dive into data collection. In this section, you’ll learn a couple different methods for getting data into Keen IO, and how we structure the events you capture. You’ll also be introduced to the example dataset we’ll use to create a beautiful, actionable dashboard.

The most basic way to load data into Keen IO is to send events as they happen, along with their associated data. An event can be any action such as a click, pageview, signup, or conversion, to name just a few. As a test, you can use cURL, a simple data transfer program built into most operating systems, to post your first event to Keen IO. Run this from a command line (you can access this in the Terminal application on a Mac, for instance):

curl "https://api.keen.io/3.0/projects/PROJECT_ID/events/testing?api_key=WRITE_KEY" -H "Content-Type: application/json" -d '{"advertiser": "Dunder Mifflin","campaign_id": 2}'

There are two fields you need to fill in from your project page. If you have not yet, create a project, and you will see the PROJECT_ID listed below your project name. Click the Show API Keys button to display your WRITE_KEY.

Once you’ve successfully added the event via the API, the Event Explorer on the project page can show your latest events. Select the testing collection from the dropdown. We named the collection testing in our cURL command:

curl "https://api.keen.io/3.0/projects/PROJECT_ID/events/testing?api_key=WRITE_KEY" -H "Content-Type: application/json" -d '{"advertiser": "Dunder Mifflin","campaign_id": 2}'

You can use any collection name you want and it will be created upon receiving its first event. Here’s how our example event above might look:

{
    "advertiser": "Dunder Mifflin",
    "campaign_id": 2,
    "keen": {
        "timestamp": "YYYY-MM-DDTHH:MM:SS.sssZ",
        "created_at": "YYYY-MM-DDTHH:MM:SS.sssZ",
        "id": "1234567890abcdef12345678"
    }
}

As expected, the event contains our two fields that we sent as JSON data. Further, there’s a “keen” object with three values. The id is a unique identifier for each event sent to Keen, the timestamp is a field that a user can overwrite, and created_at is the time that the event was created.

Most Keen IO customers use one of our SDK libraries to write events at scale, such as from active web or mobile applications. The data you send can describe device state, visitor data, user actions, or anything you want to visualize later.

In fact, you could send all of those different types of data in a single call, if you wanted. The JSON can be nested, for easy separation. The advertiser data you sent in the cURL call is actually within an “ad” object in the full browser data we’ll be using to create your first dashboard. Here’s a complete event from that sample data:

{
  "user": {
    "device_info": {
      "device": {
        "family": "Other"
      },
      "os": {
        "major": "10",
        "patch_minor": null,
        "minor": "7",
        "family": "Mac OS X",
        "patch": null
      },
      "browser": {
        "major": "11",
        "minor": "0",
        "family": "Firefox",
        "patch": null
      }
    },
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:11.0) Gecko/20100101 Firefox/11.0",
    "ip_address": "192.0.0.291",
    "geo_info": {
      "province": "Massachusetts",
      "city": "North Dartmouth",
      "postal_code": "02747",
      "continent": "North America",
      "country": "United States"
    },
    "id": "2c8d9700-d530-11e3-8b2e-0025902d99b8"
  },
  "ad": {
    "advertiser": "Dunder Mifflin",
    "campaign_id": 2
  },
  "page": {
    "url": "http://funny-videos.com/video/91981717717",
    "path": "/video/91981717717",
    "domain": "funny-videos.com",
    "protocol": "http"
  }
}

If you have a lot of data you want to load, you can use bulk load data in JSON or CSV format using our command line interface. To overwrite the timestamp, create a keen.timestamp header for your CSV or nest within a “keen” object in your JSON data.

To save time, we’ll use a public version of the browser sample data to create your first dashboard. This sample dataset is based on more than 10,000 “pageview” events, each containing some version of the sample user, ad, and page data.

Visualize with Charts on a Dashboard

Once you’ve started collecting data, you’ll be eager to visualize it in a dashboard. When you choose your metrics, you likely also thought about multiple ways to show them. Your dashboard is where you’ll make that happen.

The focus of a dashboard should be the data, so there’s no reason to start anew when there are great examples already in the public domain. For this project, we’ll pick up a responsive dashboard template for Bootstrap, another Keen IO project. There are a bunch of layouts to choose from and examples to inspire you. To get started, download the zip file from the GitHub repository.


Layouts


Once you decompress the zip file, navigate to the layouts folder. You’ll see eight folders corresponding to the options listed on GitHub. For this project we’ll use the two-and-one layout, with two side by side square charts that sit atop a wide chart.

It doesn’t really matter which you choose right now–it’s really easy to switch later because the majority of the visualization will come from the charting library. A chart can easily be placed into any layout slot, though some orientations may be better than others to show certain types of data. A long or detailed time series, for example, can benefit from a wider layout slot. On the other hand, a pie chart would be fine for a square slot.

To add your first chart, open up two-and-one/index.html in your favorite text or code editor. Open up the same file in your web browser, so you can get a feel for the layout without any charts. You don’t need to create any server-side component to display a dashboard, so everything we do in this guide will be visible on your local machine.


Layout


The dimensions on your chart slots will be a little different. Resize your browser and the dimensions will change. These layouts are responsive to different sized windows, even on phones and tablets.

Return to your text editor and find the first of these HTML blocks, about halfway down the file:

<div class="chart-stage">
  <img data-src="holder.js/100%x350/white">
</div>

You can remove the <img> tag and leave that <div> empty. Then add an id attribute to the <div>. The result should look something like this:

<div class="chart-stage" id="chart-01">
</div>

The chart ID will be the “hook” we use to tell our JavaScript code where to put the chart. For this first chart, add the following script to your HTML page, just above the </body> tag:

<script>
var client = new Keen({
  projectId: "5368fa5436bf5a5623000000",
  readKey: "3f324dcb5636316d6865ab0ebbbbc725224c7f8f3e8899c7733439965d6d4a2c7f13bf7765458790bd50ec76b4361687f51cf626314585dc246bb51aeb455c0a1dd6ce77a993d9c953c5fc554d1d3530ca5d17bdc6d1333ef3d8146a990c79435bb2c7d936f259a22647a75407921056"

});
Keen.ready(function(){
  // ----------------------------------------
  // Sample one
  // ----------------------------------------
  var pageviews_timeline = new Keen.Query("count", {
    event_collection: "pageviews",
    interval: "hourly",
    group_by: "user.device_info.browser.family",
    timeframe: {
      start: "2014-05-04T00:00:00.000Z",
      end: "2014-05-05T00:00:00.000Z"
    }
  });
  client.draw(pageviews_timeline, document.getElementById("chart-01"), {
    chartType: "areachart",
    title: false,
    height: 250,
    width: "auto",
    chartOptions: {
      chartArea: {
        height: "85%",
        left: "5%",
        top: "5%",
        width: "80%"
      },
      isStacked: true
    }
  });
  // ----------------------------------------
  //  End sample one
  // ----------------------------------------
  // ----------------------------------------
  // Sample two
  // ----------------------------------------

  // ----------------------------------------
  // End sample two
  // ----------------------------------------
  // ----------------------------------------
  // Sample three
  // ----------------------------------------

  // ----------------------------------------
  // End sample three
  // ----------------------------------------
});
</script>

The projectId and readKey values are based on the sample dataset discussed previously. When you incorporate your own data, you’ll want to replace these with your own projectId and readKey from your Keen IO project page. If you have a common set of queries that you run, you can use the Explorer to copy and paste the javascript code for these queries and plug them right into your dashboard!


Embed Button


Embed Code


Run a query on your data in the explorer, click the </> button to see the Javascript for it!

For this example project, the only thing you may need to change is to replace “chart-01” with the ID you used in your HTML. While the rest may look like a lot of code, there are just a couple of calls required to create this first chart: initialize the client variable, describe the query to get the data, and then describe the chart to draw.

In this first example, we are showing an area chart of pageviews per browser over each hour of a 24 hour period. There are a number of other options described in the Visualize section, but we’ll use two more for the subsequent charts.

Back to the JavaScript portion of your HTML file, add the following in the section prepared for sample two:

  // ----------------------------------------
  // Sample two
  // ----------------------------------------

  var pageviews_static = new Keen.Query("count", {
    event_collection: "pageviews",
    group_by: "user.device_info.browser.family",
    timeframe: {
      start: "2014-05-01T00:00:00.000Z",
      end: "2014-05-05T00:00:00.000Z"
    }
  });
  client.draw(pageviews_static, document.getElementById("chart-02"), {
    chartType: "piechart",
    title: false,
    height: 250,
    width: "auto",
    chartOptions: {
      chartArea: {
        height: "85%",
        left: "5%",
        top: "5%",
        width: "100%"
      },
      pieHole: .4
    }
  });

  // ----------------------------------------
  // End sample two
  // ----------------------------------------

Like sample one, this is showing browser pageviews. However, this extends to five days worth of data, but uses a per-browser total, rather than slicing by the hour. And instead of an area chart, this is displayed as a pie chart.

As with the previous example, you may need to change the “chart-02” if you altered the <div> ID.

To close out the sample charts, paste the following in the section prepared for sample three:


  // ----------------------------------------
  // Sample three
  // ----------------------------------------

  var impressions_timeline = new Keen.Query("count", {
    event_collection: "impressions",
    group_by: "ad.advertiser",
    interval: "hourly",
    timeframe: {
      start: "2014-05-04T00:00:00.000Z",
      end: "2014-05-05T00:00:00.000Z"
    }
  });
  client.draw(impressions_timeline, document.getElementById("chart-03"), {
    chartType: "columnchart",
    title: false,
    height: 250,
    width: "auto",
    chartOptions: {
      chartArea: {
        height: "75%",
        left: "10%",
        top: "5%",
        width: "60%"
      },
      bar: {
        groupWidth: "85%"
      },
      isStacked: true
    }
  });

  // ----------------------------------------
  // End sample three
  // ----------------------------------------

Here we are querying hypothetical advertisement impressions over a one day period, with hourly slices all grouped by advertiser. This is very similar to the query in sample one, but here the data is visualized as a column chart instead.

Load up your HTML file with these three samples and you have your first complete dashboard. Now might be the time to get back to the collect your data section and replace this data with your own. Then it’s time to get this dashboard in front of the people who need to see it.

Share with Your Team

Once you have metrics that are the drivers of your business or otherwise help you better understand your customers, you want to make sure everyone in the company has access to the insights displayed in your dashboard. There are endless ways you can share your dashboard, but here are a few with varying levels of publicity and shareability.

Since the dashboard is a simple HTML page that does not need a server, it can be stored anywhere. In this guide, we simply used the page on your local computer. If you expect the dashboard will not change much and won’t need a wide audience, you could simply keep it on your desktop and email it as an attachment. While that is the simplest method and will always have the latest data, you won’t be able to change the metrics in the dashboard without redistributing the file.

Another option is to use a file syncing service and share the file that way. Whenever you make a change to your version of the file, that change would be propagated to anyone with access.

A more advanced option would be to include the dashboard in an existing intranet, so anyone who logs in would be able to see the metrics that you’ve deemed most important. Other similar locations are an administrative panel of a website, or in a password-protected directory on a website.

Some dashboards, such as those for open source projects, can be public. In that case, GitHub Pages could be good location for simple hosting of your dashboard.

The important part here is to make this dashboard visible to those who need to see it and take actions based on what they see. If you’re able, make sure it’s somewhere that can be easily-updated, so that everyone always has access to your latest insights.

Example Dashboards

If you need some inspiration, consider these examples: