Keen IO JavaScript SDK (v3.4.0-rc)
Documentation
Docs have been moved into the master branch, so they stay in sync with each release. Check out the latest 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.4.0-rc/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.4.0-rc/keen.min.js" type="text/javascript"></script>
or
<script src="//cdn.jsdelivr.net/keen.js/3.4.0-rc/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",
writeKey: "YOUR_WRITE_KEY",
readKey: "YOUR_READ_KEY"
});
</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:
var client = new Keen({
projectId: "YOUR_PROJECT_ID",
writeKey: "YOUR_WRITE_KEY"
});
var purchaseEvent = {
item: "golden gadget",
price: 2550,
referrer: document.referrer,
keen: {
timestamp: new Date().toISOString()
}
};
client.addEvent("purchases", purchaseEvent, function(err, res){
if (err) {
}
else {
}
});
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:
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
}
]
};
client.addEvents(multipleEvents, function(err, res){
if (err) {
}
else {
}
});
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',
timeframe: "YOUR_TIMEFRAME"
});
Example Usage
var client = new Keen({
projectId: "YOUR_PROJECT_ID",
readKey: "YOUR_READ_KEY"
});
Keen.ready(function(){
var count = new Keen.Query("count", {
eventCollection: "pageviews",
groupBy: "property",
timeframe: "this_7_days"
});
client.run(count, function(err, res){
if (err) {
}
else {
}
});
});
Read more about advanced queries in our query guide.
Saved Queries
Results for a single saved query can also be retrieved by passing the saved query name into client.run("saved-query-name", callback)
.
Important: Visualizing saved query results with client.draw()
is not yet supported, but will be added soon!
var client = new Keen({
projectId: "YOUR_PROJECT_ID",
readKey: "YOUR_READ_KEY"
});
Keen.ready(function() {
client.run("saved-query-name", function(err, res) {
if (err) {
}
else {
}
});
});
Saved Queries can also be accessed and managed with the client.savedQueries()
method, which contains CRUD actions for interacting with the saved queries API resource.
.all(callback)
: Return all saved queries for the given project.get("saved-query-name", callback)
: Return a single saved query by name.create("saved-query-name", configuration, callback)
: Create a new saved query of a given name.update("saved-query-name", configuration, callback)
: Update a saved query of a given name.destroy("saved-query-name", callback)
: Destroy a saved query of a given name
Example Usage
var client = new Keen({
projectId: "YOUR_PROJECT_ID",
masterKey: "YOUR_MASTER_KEY"
});
Keen.ready(function() {
var savedQueries = client.savedQueries();
savedQueries.all(function(err, res) {
if (err) {
}
else {
}
});
savedQueries.get("saved-query-name", function(err, res) {
if (err) {
}
else {
}
});
savedQueries.create("saved-query-name",
{
refresh_rate: 0,
query: { ... },
metadata: {
display_name: "saved query name",
...
}
},
function(err, res) {
if (err) {
}
else {
}
}
);
savedQueries.update("saved-query-name",
{ refresh_rate: 86400 },
function(err, res) {
if (err) {
}
else {
}
}
);
savedQueries.destroy("saved-query-name", function(err, res) {
if (err) {
}
else {
}
});
});
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
var client = new Keen({ });
Keen.ready(function(){
var count = new Keen.Query("count", {
eventCollection: "pageviews",
groupBy: "visitor.geo.country",
interval: "daily",
timeframe: "this_21_days"
});
client.draw(count, document.getElementById("chart-wrapper"), {
chartType: "columnchart",
title: "Custom chart title"
});
var chart = new Keen.Dataviz()
.el(document.getElementById("chart-wrapper"))
.chartType("columnchart")
.prepare();
var req = client.run(query, function(err, res){
if (err) {
chart.error(err.message);
}
else {
chart
.parseRequest(this)
.title("Custom chart title")
.render();
}
});
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 contact@keen.io