kissmetrics-js

Kissmetrics JavaScript library for the client and server

Kissmetrics JS

A small library to interact with Kissmetrics that can be shared across a client (browser) and server (Node.js).

The minified source is under 3k, compared to about 20k for the version served by Kissmetrics. If you gzip the minified source, it is about 1k (Kissmetrics does not gzip their JavaScript for backward compatability reasons with older browsers). The only feature missing is the "automatic" events that Kissmetrics will record for you. These are things like page views or site visits. Since only Kissmetrics has access to the options you've sent, it's not possible to know which events you want to record automatically without using their JavaScript. For that trade off you save 95% of the file size and can use the same library on the client and server.

In place of a more detailed readme, the annotated source is very thorough.

Install from NPM with: npm install kissmetrics-js

In a browser, load the compiled JavaScript.

<script src="min/kissmetrics.min.js"></script>
<script>
km = new KissmetricsClient(API_KEY, user.name);
// ...
</script> 

In Node.js, you probably just want to require the module.

KM = require('kissmetrics-js');
km = new KM(API_KEY, user.name);
// ... 

Record data about a logged in user.

// General activity 
km = new KissmetricsClient(API_KEY, user.name);
km.record('Published post');
km.set({last_seen: new Date()});
 
// Change username 
km.record('Change username');
km.alias(user.name);

Record data about a logged out user.

// New visitor 
km = new AnonKissmetricsClient(API_KEY);
km.record('Visited front page');
km.record('Visited signup form');
 
// Signs up 
km.record('Signed up');
km.alias(user.name);
 
// Record more data as the new logged in user 
km = new KissmetricsClient(API_KEY, user.name);
km.record('Publish post');

Automatically-generated ID's are deleted from storage by default when alias() is called, but you have the option to save them by passing a second argument of false.

km = new AnonKissmetricsClient(API_KEY);
km.record('Signed up').alias(user.name);
console.log(km._storage.get());
// null 
 
km = new AnonKissmetricsClient(API_KEY);
km.record('Signed up').alias(user.name, false);
console.log(km._storage.get());
// "56a44b65ddad8a4ab00885ec42e7d2f7db46dcd69c3f" 

Data methods can be chained.

km = new AnonKissmetricsClient(API_KEY);
km.record('Visited front page')
    .record('Visited signup form')
    .record('Signed up')
    .alias(user.name)
    .record('Published post');

Calling alias() updates the instance's person attribute, so future data is recorded using the new identity.

km = new KissmetricsClient(API_KEY, 'evan');
console.log(km.person);
// evan 
 
km.alias('evansolomon');
console.log(km.person);
// evansolomon 
 
km.record('foobar');
// Recorded as "evansolomon" doing "foobar"