bigby-tracker v0.0.8

bigby-tracker

web tracking for analytics

Install with:

yarn add git+ssh://git@github.com/stitchfix/bigby-tracker#v0.0.8

Include in your application with:

var {track, setStateFn, setUsername} = require('bigby-tracker').createTracker()

or

import createTracker from 'bigby-tracker'
var {track, setStateFn, setUsername} = createTracker()

There are three functions that are exported: track(), setStateFn(), and setUsername(). The only one of those that you need is track().

track()

track() is, unsurprisingly, the core. You can track a string, which gets set as the "action" of the event, or you can pass it an object, which just needs an action property, or you can pass it a string (the action) and an object. The entire object will be logged, via JSON, so you probably want to make sure it is JSON serializable.

track('someone did a thing')     // event will be {"action": "someone did a thing"}

track('someone did a thing', {item_id: 125212})

// event will be {"action": "someone did a thing", "item_id": 125212}

track({
  action: 'someone did a thing', // 'action' property is required
  item_id: 125212,               // everything else is free-form and optional
  more_info: {a: 'data'}         // can be deeply nested, just make sure it's JSON serializable
})

setStateFn()

If your web app has some state you want to track across all tracked actions (React, I'm looking at you), you can pass setStateFn() a function that returns an object that will be logged alongside each event, like so:

import React from 'react'
import createTracker from 'bigby-tracker'
var {track, setStateFn} = createTracker()

const App = React.createClass({
  ...
  provideTrackingState () {
    return {
      shipment_id: this.props.shipment_id,
      client_id: this.state.client_id,
    }
  },
  componentWillMount () {
    setStateFn(this.provideTrackingState)
  }
  ...
}

setUsername()

setUsername() is even simpler: if you have some idea of who your user is, just use setUsername(username) to set it. Note that if users are logged in via sloth, their username and email will be automagically determined and added to the tracking events.

Configuration

You can configure the tracker by passing an options object into createTracker. Any options not explicitly set will use the following defaults:

{
  logMethod: 'post',        // valid values are: 'post', 'console', 'none'
  routingKey: 'sf.algo.web_tracking.bigby',  // routes to events.web_client_event hive table
  logErrors: true,
}

Development mode

If you want to log to the console on localhost (where you're probably developing), you can do something like:

import createTracker from 'bigby-tracker'
var {track} = createTracker(
  (location.hostname === 'localhost') ? {logMethod: 'console'} : {}
)

The following JSON is POSTed to otherworld, where it gets sent on to the events.web_client_event table in hive:

{
  event: {
    action: "test"                   // or more, if you passed track() an object
  },
  state: {},                         // whatever the setStateFn returns
  type: "user tracking",             // errors have type: 'error'
  timestamp: 1450214872847,          // browser timestamp
  url: "http://whatever.com/index.html",
  uuid: "edb04b4e-784f-4860-b53f-8cd692215bf8",  // unique to window
  eventSequence: 1,                  // auto-incrementing sequence, page init = 0
  environment: {
    windowDims: {w:661,h:904},   // window dimensions in pixels
    screenDims: {w:1680,h:1050}, // screen dimensions in pixels
    scroll: {x:0,y:0},           // scroll of main viewport
    devicePixelRatio: 2,             // retina / HiDpi screen?
    browser: {
      ua: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.80 Safari/537.36",
      name: "Chrome",
      version: "47.0.2526.80",
      os: "OS X",
      osVersion: "10.11.2"
    },
    timezoneOffset: 480
  },
  user: {
    slothStitchFixEmail: "trached@stitchfix.com", // automatically set if
    slothStitchFixUsername: "trached"             // authenticated via sloth
  },
  msSincePageStart: 29               // milliseconds since page was loaded
}

Clientside Javascript errors get sent to the same place, with "type": "error" no $.event or $.state, and the complete error in $.error. The following attributes are set in $.error:

{
  errMsg,    // Error message (string)
  url,       // URL of the script where the error was raised (string)
  lineNum,   // Line number where error was raised (number)
  colNum,    // Column number for the line where the error occurred (number)
  error      // Error Object (object)
}

sample data access

# sample code to pull events from events.web_client_event via pyhive

from pyhive import presto
cursor = presto.connect('ec2-52-91-96-167.compute-1.amazonaws.com', port=8889).cursor()
cursor.execute('''select
json_extract(payload, '$.event.action')
, payload
from events.web_client_event
where 1 = 1
---  AND json_extract_scalar(payload, '$.event.action') != 'page init'
    AND regexp_like(
        json_extract_scalar(payload, '$.url'),
        '^https://minxler.sloth.vertigo.stitchfix.com/studies/training-day-one'
    )
ORDER BY json_extract_scalar(payload, '$.eventSequence')
limit 1
​
''')
print cursor.fetchall()
# print cursor.fetchone()