tracking.js v0.1.1

Tracking

An event tracking javascript library that is built on top of AWS Kinesis Firehouse, AWS API Gateway, AWS ElasticSearch, and S3.

About The Black Tux

The Black Tux is reinventing the formalwear rental industry so guys can show up at their best on the days that matter most. The company designs and manufactures modern rental suits and tuxedos that actually fit—made of 100% wool, ordered online or in one of our showrooms, and delivered for free. Using a combination of machine learning, tailor-trained fit specialists, and industry-leading customer service, The Black Tux guarantees a perfect fit every time.

To support this elevated customer experience we rely on lots of technology. From time to time we release things we build to the open source community when we feel they might be useful by others as well, and of course don't include anything proprietary.

How to use

Before you can start, we do require that AWS Kinesis Firehouse, API Gateway, ElasticSearch and S3 all get setup. We will eventually add that as a script, but for now you must do that by hand, and then you can use the below.

Keep in mind this currently works for IE 10+ and all other modern browsers.

Installation

Including as a script

Use the following line in the header of your HTML files:

<script>/MSIE \d|Trident.*rv:/.test(navigator.userAgent)?document.write('<script src="https://www.promisejs.org/polyfills/promise-7.0.4.min.js"></script><script src="tracking.min.js"></script>'):document.write('<script src="tracking.min.js"></script>');</script>

Then once up, edit the AWS_URL variable in the tracking.js, minify it and now it's ready for inclusion in any document.

Using with npm

By default, this library points to a specific hard-coded AWS endpoint (blank in the publicly released version). To specify a different endpoint for development or staging, require it as a module. Add the following to your package.json dependencies:

"dependencies": {
  ...
  "tbt-tracking": "git://github.com/TheBlackTuxCorp/tracking.git#master",
  ...
}

And then in your application, use like so:

const tracking = require('tbt-tracking')
tracking.init(/* AWS_URL goes here*/)

API

Use the _load, _prop and _trigger functions to execute the options you want.

_load

The _load function kicks things off and should be used before any other property (although there are promises to help ensure it executes in the right order). This function is used to load the tracking application and provide some identifying information about the user.

Currently the function parameters are email, the application/page the person is on and the callback function.

_prop

The _prop function is for providing properties to the tracking event. These could be things like the order_id, product, discount, user_id of the profile being viewed, etc. The properties should not be used to store entity information. We should assume that the use case is to know an action happened and be able to link back to that action, to then view the results of the action.

Properties are sent as key, value, callback. As many properties can be called as you wish. Calling _load again will clear the properties.

Example: You are on the Admin application and applying a discount to an order. We will want the order_id, to link back to, but we will not store the discount applied.

_trigger

The _trigger function is used to save the action and information. A trigger can be fired multiple times on a page for each action taken. Each event will be stored with the identifying information, the properties that were set and the action.

This function takes four parameters: category, action, object and the callback.

Using our example of a discount being applied to an order, the Category would like be Order Adjustments, the action would be that a discount was applied, and the object is how it was applied - generally something like the submit button id.