Deprecation notice!
We have consolidated our JS-powers with the release of keen-js. All functionality from this project has been moved over, along with a bunch of new goodies.
Install keen-js
$ npm install keen-js
Minor changes in client instantiation:
// change this...var client = Keen; // ...into thisvar client = {};
Scoped key en/decryption has also moved, but is documented here.
This repo will remain active for documentation purposes, but all issues, feature requests, general questions, thoughts, concerns, hopes and dreams should all happen within the keen-js project going forward.
Documentation below is for the original (now deprecated) KeenClient-Node SDK
Keen IO - NodeJS
Keen IO is an online service to collect, analyze, and visualize your data.
Getting Started
Use npm to install!
npm install keenio
Examples
Initialization
var Keen = ; // Configure instance. Only projectId and writeKey are required to send data.var client = Keen;
You can also have multiple instances if you are connecting to multiple KeenIO accounts in the one project (probably edge case).
var Keen = ; // Configure instance with API Keyvar client1 = Keen;var client2 = Keen;
In the future there will be the ability to pass options into the initialisation such as batching inserts, etc. The structure of this hasn't been defined yet but will look something like the following.
var Keen = ; // Configure instance with API Key and optionsvar client = Keen;
Send Events
var Keen = ;var client = Keen; // send single event to Keen IOclient; // send multiple events to Keen IOclient;
Generate Scoped Key
var Keen = ;var apiKey = "YOUR_API_KEY";var scopedKey = Keen;var client = Keen;
Queries
Analyses are first-class citizens, complete with parameter getters and setters.
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.
Format:
var your_analysis = analysisType params;
Example Usage
var Keen = ;var client = Keen; var count = "count" event_collection: "pageviews" group_by: "property" timeframe: "this_7_days"; // Send queryclient;
Query Analysis Types
All of the following analyses require an event_collection
parameter. Some analyses have additional requirements, which are noted below.
count
count_unique
sum
requires a target_property
parameter, where value is an integer
average
requires a target_property
parameter, where value is an integer
maximum
requires a target_property
parameter, where value is an integer
minimum
requires a target_property
parameter, where value is an integer
select_unique
requires a target_property
parameter
extraction
A note about extractions: supply an optional email
attribute to be notified when your extraction is ready for download. If email is not specified, your extraction will be processed synchronously and your data will be returned as JSON.
Keen.Funnel
requires a steps
attribute
A note about funnels: funnels require a steps
as an array of objects. Each step requires an event_collection
and actor_property
parameter.
var funfunfunnel = 'funnel' steps: event_collection: "view_landing_page" actor_property: "user.id" event_collection: "signed_up" actor_property: "user.id" timeframe: "this_6_months";
Learn more about funnels in the API reference
Run multiple analyses at once
The <Client>.run
method accepts an individual analysis or array of analyses. In the latter scenario, the callback is fired once all requests have completed without error. Query results are then returned in a correctly sequenced array.
Query results are also attached to the query object itself, and can be referenced as this.data
.
var avg_revenue = "average" event_collection: "purchase" target_property: "price" group_by: "geo.country";var max_revenue = "maximum" event_collection: "purchase" target_property: "price" group_by: "geo.country"; var mashup = client;
Get/Set Parameters and Refresh Queries
// Based on previous example // Update parametersavg_revenue;max_revenue; // Re-run the querymashup;
Future Updates
Future module updates are planned to introduce the remaining API calls. You can see some sketches for these in the examples directory. Also, as mentioned above, specifying options when creating an instance to configure the behaviour of the instance (ie, batching event submissions).
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!
Further Reading
Keen IO - API Technical Reference
Release History
0.0.4
- Update dependencies.
0.0.3
- Support generating Scoped Keys.
0.0.2
- Change error for blank write key.
0.0.1
- Add write/read keys.
- Reworked interface - not backwards compatible with 0.0.0!
0.0.0
- First release.
License
Licensed under the MIT license.