keen-js

Keen IO JavaScript SDK (v3.2.7)

Important: v3.2.0 introduced several breaking changes from previous versions. Check out the Changelog before upgrading.

Charts issue: A recent update to the Google Visualization API is causing charts to fail in earlier versions of this library. To resolve the issue, simply update from v3.0.x to v3.1.0. This is a safe upgrade with no breaking changes from earlier affected versions. Read about this release here.

Documentation

Docs have been moved into the master branch, so they stay in sync with each release. Check out the latest here.

v3.1.0 docs are here, and v2 docs are way back here.

Get Project ID & API Keys

If you haven’t done so already, login to Keen IO to create a project. The Project ID and API Keys are available on the Project Overview page. You will need these for the next steps.

Install the library

# via npm
$ npm install keen-js

# or bower
$ bower install keen-js

To start recording events from your website or blog, copy/paste this snippet of JavaScript above the </head> tag of your page:

<script type="text/javascript">
  !function(a,b){a("Keen","https://d26b395fwzu5fz.cloudfront.net/3.2.7/keen.min.js",b)}(function(a,b,c){var d,e,f;c["_"+a]={},c[a]=function(b){c["_"+a].clients=c["_"+a].clients||{},c["_"+a].clients[b.projectId]=this,this._config=b},c[a].ready=function(b){c["_"+a].ready=c["_"+a].ready||[],c["_"+a].ready.push(b)},d=["addEvent","setGlobalProperties","trackExternalLink","on"];for(var g=0;g<d.length;g++){var h=d[g],i=function(a){return function(){return this["_"+a]=this["_"+a]||[],this["_"+a].push(arguments),this}};c[a].prototype[h]=i(h)}e=document.createElement("script"),e.async=!0,e.src=b,f=document.getElementsByTagName("script")[0],f.parentNode.insertBefore(e,f)},this);
</script>

Or load the library synchronously from our CDN:

<script src="https://d26b395fwzu5fz.cloudfront.net/3.2.7/keen.min.js" type="text/javascript"></script>

or

<script src="//cdn.jsdelivr.net/keen.js/3.2.7/keen.min.js" type="text/javascript"></script>

Read our Installation guide to learn about all the ways this library can fit into your workflow.

Configure a new Keen JS client

When instantiating a new Keen JS client, there are a number of possible configuration options. A projectId is required at all times, and writeKey and readKey are required for sending or querying data, respectively.

<script type="text/javascript">
  var client = new Keen({
    projectId: "YOUR_PROJECT_ID", // String (required always)
    writeKey: "YOUR_WRITE_KEY",   // String (required for sending data)
    readKey: "YOUR_READ_KEY"      // String (required for querying data)

    // protocol: "https",         // String (optional: https | http | auto)
    // host: "api.keen.io/3.0",   // String (optional)
    // requestType: "jsonp"       // String (optional: jsonp, xhr, beacon)
  });
</script>

You can configure new instances for as many projects as necessary.

Record a single event

Here is an example for recording a "purchases" event. Note that dollar amounts are tracked in cents:

// Configure an instance for your project
var client = new Keen({
  projectId: "YOUR_PROJECT_ID",
  writeKey: "YOUR_WRITE_KEY"
});

// Create a data object with the properties you want to send
var purchaseEvent = {
  item: "golden gadget",  
  price: 2550, // track dollars as cents
  referrer: document.referrer,
  keen: {
    timestamp: new Date().toISOString()
  }
};

// Send it to the "purchases" collection
client.addEvent("purchases", purchaseEvent, function(err, res){
  if (err) {
    // there was an error!
  }
  else {
    // see sample response below
  }
});

API response for recording a single event

{
  "created": true
}

Send as many events as you like. Each event will be fired off to the Keen IO servers asynchronously.

Record multiple events

Here is an example for how to record multiple events with a single API call. Note that dollar amounts are tracked in cents:

// Configure an instance for your project
var client = new Keen({...});

var multipleEvents = {
  "purchases": [
    { item: "golden gadget", price: 2550, transaction_id: "f029342" },
    { item: "a different gadget", price: 1775, transaction_id: "f029342" }
  ],
  "transactions": [
    {
      id: "f029342",
      items: 2,
      total: 4325
    }
  ]
};

// Send multiple events to several collections
client.addEvents(multipleEvents, function(err, res){
  if (err) {
    // there was an error!
  }
  else {
    // see sample response below
  }
});

API response for recording multiple events

{
  "purchases": [
    {
      "success": true
    },
    {
      "success": true
    }
  ],
  "transactions": [
    {
      "success": true
    }
  ]
}

Read more about all the ways you can record events in our tracking guide.

Wondering what else you should record? Browse our data modeling guide, and send us recommendations or pull requests if you don't find what you're looking for.

Querying events

The <Client>.run method is available on each configured client instance to run one or many analyses on a given project. Read more about running multiple analyses below.

var your_analysis = new Keen.Query(analysisType, {
  eventCollection: 'YOUR_EVENT_COLLECTION', // (required)
  timeframe: "YOUR_TIMEFRAME" // (required)
  // ... additional parameters
});

Example Usage

// Create a client instance
var client = new Keen({
  projectId: "YOUR_PROJECT_ID",
  readKey: "YOUR_READ_KEY"
});

Keen.ready(function(){

  // Create a query instance
  var count = new Keen.Query("count", {
    eventCollection: "pageviews",
    groupBy: "property",
    timeframe: "this_7_days"
  });

  // Send query
  client.run(count, function(err, res){
    if (err) {
      // there was an error!
    }
    else {
      // do something with res.result
    }
  });

});

Read more about advanced queries in our query guide.

Query Caching

Data sent to Keen is available for querying almost immediately. For use cases that don’t require up-to-the-second answers but require fast performance, query caching can be used to speed up a query. To include query caching as a feature, just add the maxAge query parameter to any other query parameters you’ve already specified. The first time your application makes a query specifying the max_age the answer will be calculated normally before it can be cached for future uses.

var count = new Keen.Query("count", {
    eventCollection: "pageviews",
    groupBy: "property",
    timeframe: "this_7_days",
    maxAge: 300 // include maxAge as a query parameter to activate Query Caching
});

maxAge is an integer which represents seconds. The maximum value for maxAge is 129600 seconds or 36 hours. Read more about Query Caching in the Keen IO Data Analysis Docs.

Tip: If you want to speed up your queries but maintain freshness, you can cache a year-long query and combine the result with a normal query that calculates the most current day’s answer.

Visualization

Building charts from queries is easier than ever.

Clients have a #draw method with accepts a query, a DOM selector, and a configuration object as arguments. You can call this directly on the client, which will execute a request and visualize its response, like so:

client.draw(query, node, config);

A future release will add the ability to plot multiple query responses on a single chart, but for the time being only the first query response will be visualized.

Example usage

// Create a client instance
var client = new Keen({ /* your config */ });

Keen.ready(function(){

  // Create a query instance
  var count = new Keen.Query("count", {
    eventCollection: "pageviews",
    groupBy: "visitor.geo.country",
    interval: "daily",
    timeframe: "this_21_days"
  });

  // Basic charting w/ `client.draw`:
  client.draw(count, document.getElementById("chart-wrapper"), {
    chartType: "columnchart",
    title: "Custom chart title"
  });

  // Advanced charting with `Keen.Dataviz`:
  var chart = new Keen.Dataviz()
    .el(document.getElementById("chart-wrapper"))
    .chartType("columnchart")
    .prepare(); // starts spinner

  var req = client.run(query, function(err, res){
    if (err) {
      // Display the API error
      chart.error(err.message);
    }
    else {
      // Handle the response
      chart
        .parseRequest(this)
        .title("Custom chart title")
        .render();
    }
  });

  // How about a chart that updates itself every 15 minutes?
  setInterval(function() {
    req.refresh();
  }, 1000 * 60 * 15);
});

Read more about building charts from query responses in our visualization guide.

Contributing

This is an open source project and we love involvement from the community! Hit us up with pull requests and issues.

The aim is to build up this module to completely represent the API provided by Keen IO, which is quite extensive. The more contributions the better!

Resources

Data Modeling Guide

API Technical Reference

API Status

Support

Need a hand with something? Shoot us an email at [e-mail]