Introducing Lil Brother: Open Source Client-Side Event Tracking

We’re happy to share a project we’ve developed that helps us understand how our customers are interacting with our site.  It’s called Lil Brother — it tracks clicks and other events in the browser, and reports back in real time.

How does it work?

First, add some client code to pull in the library and initialize a Lil Brother observer:

<script src="http://server:8000/lilbro.js"></script>

var lilBro = new LilBro({
    element: document.body,
    server: 'server:8000'

Then start up the node listener on the server side:

$ node bin/lilbro --output-file events.log

Lil Brother attaches a single event handler to a top-level container and listens for events.  As users click on links or focus inputs or check boxes, etc, the client sends those events over the wire to a listener on the server where they get recorded.

Can I have some context?

When a click happens, we gather what context we can and send that along too.  If the target element has an id and/or a class, we note that.  Otherwise, we traverse up the DOM until we find a parent’s id or class.  We also grab the element tag name, X and Y mouse coordinates relative to the element and to the page, scroll positions, and input values if the element happened to be some sort of input field.

In addition to metadata around the event, we discover other attributes too: browser version, operating system, viewport width and height, request path, and some other bits.

Visits and visitors

Of course clicks are part of a larger hierarchy.  There are users behind these clicks, and users browse in sessions.  To tie events together, Lil Brother sets two cookies: a long-lived visitor cookie, and a short-lived visit cookie.  We send the values of these cookies along so that we can string events together and aggregate later.

What next?

With the data captured on the client, sent over the wire, and recorded one way or another, Lil Brother’s job is done, and there’s much left to do yet.  From here, aggregation, visualization, analysis are now possible, and left to you.  Imagine what you can do with this data: build heat maps, visualize traffic patterns, discover customer friction points, measure behavior in A/B tests, and on and on. Have fun!