keen-tracking.js

A JavaScript tracking library for Keen. Track events, user actions, clicks, pageviews, conversions and more!

Installation

Install this package from NPM Recommended

npm install keen-tracking --save

Public CDN

<script crossorigin src="https://cdn.jsdelivr.net/npm/keen-tracking@5/dist/keen-tracking.min.js"></script>

Project ID & API Keys

Login to Keen IO to create a project and grab the Project ID and Write Key from your project's Access page.

Getting started

The following examples demonstrate how to implement rock-solid web analytics, capturing pageviews, clicks, and form submissions with robust data models.

Full documentation is available here

Using React? Check out these setup guides:

• React Flux Logger: How to instrument a Flux ReduceStore
• React Redux Middleware: How to instrument a Redux Store

Upgrading from an earlier version of keen-js? Read this.

Record an Event

import KeenTracking from 'keen-tracking';

const client = new KeenTracking({
  projectId: 'PROJECT_ID',
  writeKey: 'WRITE_KEY'
});

client
  .recordEvent('purchases', {
    item: 'Avocado',
    number_of_items: 10,
    user: {
      name: 'John Smith'
    }
  })
  .then((response) => {
    // handle successful responses
  })
  .catch(error => {
    // handle errors
  });

Automated Event Tracking

Automatically record pageviews, clicks, form_submissions and element_views events with robust data models:

<script>
  (function(name,path,ctx){ctx[name]=ctx[name]||{ready:function(fn){var h=document.getElementsByTagName('head')[0],s=document.createElement('script'),w=window,loaded;s.onload=s.onreadystatechange=function(){if((s.readyState&&!(/^c|loade/.test(s.readyState)))||loaded){return}s.onload=s.onreadystatechange=null;loaded=1;ctx[name].ready(fn)};s.async=1;s.src=path;h.parentNode.insertBefore(s,h)}}})
  ('KeenTracking', 'https://cdn.jsdelivr.net/npm/keen-tracking@5/dist/keen-tracking.min.js', this);

  KeenTracking.ready(function(){
    const client = new KeenTracking({
      projectId: 'YOUR_PROJECT_ID',
      writeKey: 'YOUR_WRITE_KEY'
    });
    client.initAutoTracking();
  });
</script>

Learn how to configure and customize this functionality here

Pageview Tracking

First, let's create a new client instance with your Project ID and Write Key, and use the .extendEvents() method to define a solid baseline data model that will be applied to every single event that is recorded. Consistent data models and property names make life much easier later on, when analyzing and managing several event streams. This setup also includes our data enrichment add-ons, which will populate additional information when an event is received on our end.

import KeenTracking from 'keen-tracking';

const client = new KeenTracking({
  projectId: 'PROJECT_ID',
  writeKey: 'WRITE_KEY'
});
const helpers = KeenTracking.helpers;
const utils = KeenTracking.utils;

const sessionCookie = utils.cookie('rename-this-example-cookie');
if (!sessionCookie.get('guest_id')) {
  sessionCookie.set('guest_id', helpers.getUniqueId());
}

// optional
client.extendEvents(() => {
  return {
    geo: {
      ip_address: '${keen.ip}',
      info: {
        /* Enriched data from the API will be saved here */
        /* https://keen.io/docs/api/?javascript#ip-to-geo-parser */
      }
    },
    page: {
      title: document.title,
      url: document.location.href,
      info: { /* Enriched */ }
    },
    referrer: {
      url: document.referrer,
      info: { /* Enriched */ }
    },
    tech: {
      browser: helpers.getBrowserProfile(),
      user_agent: '${keen.user_agent}',
      info: { /* Enriched */ }
    },
    time: helpers.getDatetimeIndex(),
    visitor: {
      guest_id: sessionCookie.get('guest_id')
      /* Include additional visitor info here */
    },
    keen: {
      addons: [
        {
          name: 'keen:ip_to_geo',
          input: {
            ip: 'geo.ip_address'
          },
          output : 'geo.info'
        },
        {
          name: 'keen:ua_parser',
          input: {
            ua_string: 'tech.user_agent'
          },
          output: 'tech.info'
        },
        {
          name: 'keen:url_parser',
          input: {
            url: 'page.url'
          },
          output: 'page.info'
        },
        {
          name: 'keen:referrer_parser',
          input: {
            referrer_url: 'referrer.url',
            page_url: 'page.url'
          },
          output: 'referrer.info'
        }
      ]
    }
  }
});

// record the event
client
  .recordEvent('pageviews', {
    // here you can add even more data
    // some_key: some_value
  })
  .then((response) => {
    // handle responses
  }).catch(error => {
    // handle errors
  });

Every event that is recorded will inherit this baseline data model. Additional properties defined in client.recordEvent() will be applied before the event is finally recorded.

What else can this SDK do?

• Automated tracking (browser-only)
• Record multiple events in batches
• Extend event data models for a single event stream
• Queue events to be recorded at a given time interval

App Frameworks:

• React Flux Logger: How to instrument a Flux ReduceStore
• React Redux Middleware: How to instrument a Redux Store
• Vue.js Vuex Store: How to instrument a Vue Vuex Store

Video Players:

• Facebook video player
• HTML5 video player
• Video.js player
• Vimeo video player
• Youtube iFrame video player

Full documentation is available here

Click and Form Submit Tracking

Clicks and form submissions can be captured with .listenTo(). This example further extends the client instance defined previously, and activates a simple timer when the page the loaded. Once a click or submit event is captured, the timer's value will be recorded as visitor.time_on_page.

import KeenTracking from 'keen-tracking';

const client = new KeenTracking({
  projectId: 'PROJECT_ID',
  writeKey: 'WRITE_KEY'
});
const helpers = KeenTracking.helpers;
const timer = KeenTracking.utils.timer();
timer.start();

KeenTracking.listenTo({
  'click .nav a': (e) => {
    return client.recordEvent('click', {
      action: {
        intent: 'navigate',
        target_path: helpers.getDomNodePath(e.target)
      },
      visitor: {
        time_on_page: timer.value()
      }
    });
  },
  'submit form#signup': (e) => {
    return client.recordEvent('form-submit', {
      action: {
        intent: 'signup',
        target_path: helpers.getDomNodePath(e.target)
      },
      visitor: {
        email_address: document.getElementById('signup-email').value,
        time_on_page: timer.value()
      }
    });
  }
});

Click events (clicks) will record specific attributes from the clicked element or its ancestor elements and pass them via the element property in the event object data:

// event object
{
    // ...

    // specific to the clicks event type
    "element": {
      "action" : undefined,                 // [DIRECT]
      "class": "cta",                       // [DIRECT]
      "href": "https://keen.io/",     // [INHERITED]
      "id": "main-cta",                     // [INHERITED]
      "event_key": "learn-more-cta",        // [INHERITED] from the `data-event-key` attribute
      "method": "learn-more-link",          // [DIRECT]
      "node_name": "A",                     // [DIRECT]
      "selector": "body > div:eq(0) > div:eq(1) > div:eq(0) > a", // [DIRECT]
      "text": "Learn More",                 // [INHERITED]
      "title": "Learn More",                // [INHERITED]
      "type": undefined,                    // [DIRECT]
      "x_position": 191,                    // [DIRECT]
      "y_position": 970                     // [DIRECT]
  }
}

In the above list of collected properties for a click event, some properties are gathered from the nearest ancestor elements if they can't be found on the immediate source element of the event. These properties are shown with [INHERITED] above.

For example, a click on the word clicked! below:

  <a href='foo.html' data-event-key='click-me-cta'>
    <span id='contrived-example'>I want to be <strong class='enhance'>clicked!</strong></span>
  </a>

Would generate an event including a mixture of immediate attributes and attributes found by traversing up the DOM tree:

{
  // ...
  "id" : "contrived-example",
  "class" : "enhance",
  "text" : "clicked!",
  "href" : "foo.html",
  "node_name" : "STRONG",
  "event_key" : "click-me-cta",
}

Note: The event_key value (data-event-key attribute) is a more explicit keen-specific identifier that gives you an option outside of href, id, and class values to group or identify and query clicks in a meaningful way without potential ID/class collisions or dual-use naming schemes.

Want to get up and running faster? This can also be achieved in the browser with automated event tracking.

Track views of the HTML elements

Use Intersection Observer to track elements that have been seen by a user. In an example the CSS selector of the HTML elements is defined as .track-element-view. Use threshold to control the sensitivity of the Observer. Note: This feature works only on the browsers that support Intersection Observer.

import KeenTracking from 'keen-tracking';

const client = new KeenTracking({
  projectId: 'PROJECT_ID',
  writeKey: 'WRITE_KEY'
});
const helpers = KeenTracking.helpers;

if(typeof IntersectionObserver !== 'undefined'){
  const elementViewsOptions = {
    threshold: 1.0,
  }
  const elementViewsCallback = (events, observer) => {
    events.forEach(el => {
      if(el.isIntersecting){
        return client
          .recordEvent({
            event_collection: 'element_views',
            event: {
              element: helpers.getDomNodeProfile(el.target)
           }
          });
      }
    });
  }
  const observer = new IntersectionObserver(elementViewsCallback, elementViewsOptions);
  const target = document.querySelectorAll('.track-element-view');
  target.forEach(el => {
    observer.observe(el);
  });
}

Block Bots and Improve Device Recognition

Install mobile-detect.js to identify basic device types and block noisy bots and crawlers.

npm install mobile-detect --save

This example further extends the client instance defined above, inserting a new tech.device_type property with three possible values: 'desktop', 'mobile', and 'tablet'. If the user agent is determined to be a bot, it may be ideal to abort and avoid recording an event.

import MobileDetect from 'mobile-detect';

const md = new MobileDetect(window.navigator.userAgent);
if (md.is('bot')) {
  return false;
}

// extends client instance defined previously
client.extendEvents(() => {
  return {
    tech: {
      device_type: md.tablet() ? 'tablet' : md.mobile() ? 'mobile' : 'desktop'
    }
  };
});

Check out the many additional methods supported by mobile-detect.js to further enrich your data model.

This can also be used with automated event tracking.

Server-side Event Tracking

const KeenTracking = require('keen-tracking');

const client = new KeenTracking({
  projectId: 'PROJECT_ID',
  writeKey: 'WRITE_KEY'
});

// promise
client
  .recordEvent('purchases', {
    item: 'Avocado',
    number_of_items: 10,
    user: {
      name: 'John Promise'
    }
  })
  .then((response) => {
    // handle successful responses
  })
  .catch(error => {
    // handle errors
  });

// or callback
client
  .recordEvent('purchases', {
    item: 'Avocado',
    number_of_items: 10,
    user: {
      name: 'John Callback'
    }
  }, (error, response) => {
    if (error) {
      // handle errors
      return;
    }
    // handle responses
  });

Cancel request

const KeenTracking = require('keen-tracking');

const client = new KeenTracking({
    projectId: 'PROJECT_ID',
    writeKey: 'WRITE_KEY'
});

const query = client
  .recordEvent('purchases', {
    item: 'Avocado',
    number_of_items: 10,
    user: {
      name: 'John Promise'
    }
  })

// cancel
query.abort();

// handling response and cancel
query.then(res => {
    // response
}).catch((err) => {
    if (err === 'REQUEST_ABORTED') {
        // request canceled
    }
});

In browser environment make sure to attach AbortController polyfill to support browsers which do not have that feature. You can do it by adding this script on your website:

https://cdn.jsdelivr.net/npm/[email protected]/dist/umd-polyfill.min.js

Handling connection problems

When KeenTracking encounters connection problems, it will retry to send the data.

import KeenTracking from 'keen-tracking';

const client = new KeenTracking({
  projectId: 'PROJECT_ID',
  writeKey: 'WRITE_KEY',

  // customize the default values
  retry: {
    limit: 10, // how many times retry to record an event
    initialDelay: 200, // initial delay between consecutive calls.
    // Each next retry will be delayed by (2^retries_count * 100) milliseconds,
    retryOnResponseStatuses: [ // array of invalid http response statuses
      408,
      500,
      502,
      503,
      504
    ]
  }
});

Unique events

Save the event only once.

client
  .recordEvent({
    event_collection: 'unique_clicks',
    event: {
      some_key: 'some_value',
      // ...
    },
    unique: true, // check if the event is unique, before sending to API
    cache: {
      storage: 'indexeddb', // for persistence. Remove this property to use RAM
      hashingMethod: 'md5', // remove this property to store as a stringified json
      maxAge: 1000 * 60, // store the information about unique value for 60 seconds
    }
  })
  .then((response) => {
    console.log('ok', response);
  })
  .catch(someError => {
    console.log('error', someError);
  });

Request types

By default, we make requests using the Fetch API.

For UI interactions, consider using the BeaconAPI. It's the fastest non-invasive way to track user behaviour. Due to its nature, BeaconAPI runs requests in the background, with no possibility to handle errors. If you want to handle errors, you need to use the Fetch API.

// specify request types for all requests
const client = new KeenTracking({
  projectId: 'PROJECT_ID',
  writeKey: 'WRITE_KEY',
  requestType: 'fetch' // fetch, beaconAPI, img
});

// you can use different requestType for a single request
client
  .recordEvent({
    event_collection: 'clicks',
    event: {
      some_key: 'some_value',
      // ...
    },
    requestType: 'beaconAPI'
  });

Custom Host

You can set a custom domain for requests

const client = new KeenTracking({
  projectId: 'PROJECT_ID',
  writeKey: 'WRITE_KEY',
  host: 'somehost.com'
});

Recorded Event ID

A successful response from our API does not contain the ID of the newly created event. We are using Cassandra Database (NoSQL), so there are no joins. Store all necessary data in each event you record. Denormalization and duplication of data is a fact of life with Cassandra. Read more:

• Cassandra Modeling Guide
• How not to use Cassandra

Tracking Opt-Out

It's easy to build tracking opt-out functionality. If opt-out is set to true no data is recorded.

You can set up opt-out by defining client instance

const client = new KeenTracking({
  projectId: 'PROJECT_ID',
  writeKey: 'WRITE_KEY',
  optOut: true
});

or by invoking client.setOptOut(true) method

client.setOptOut(true);

Note: The user can block tracking in the browser by doNotTrack setting. We can respect or overwrite this setting by defining client instance

const client = new KeenTracking({
  projectId: 'PROJECT_ID',
  writeKey: 'WRITE_KEY',
  respectDoNotTrack: true // it's false by default
});

Contributing

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

Learn more about contributing to this project.

Support

Need a hand with something? Shoot us an email at [email protected]. We're always happy to help, or just hear what you're building! Here are a few other resources worth checking out:

• Feature requests
• API status
• API reference
• How-to guides
• Data modeling guide
• Slack (public)