by shutterstock

shutterstock / lil-brother

Track clicks and other client-side events on web pages

218 Stars 36 Forks Last release: Not found MIT License 38 Commits 0 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Li'l Brother

Li'l Brother tracks clicks on web pages, without blocking any interaction.


Include the library:

Listen for clicks on the body:

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

LilBro Options


Reference to top-level container element to monitor for events.


Server to communicate with over HTTP calls.


Server to communicate with over HTTPS calls.

visitidcookie, visitoridcookie

Custom cookie names for visit and visitor cookies. Defaults to


If set to true, will log focus/blur events that occur.


Optional base template object for events; useful for attatching extra metadata.

LilBro Methods

write({ event_type: ..., ... })

Write an event to the server. Parameters are merged in with the event on its way out. For example, to fire off a page load event:

lilBro.write({event_type: 'page_load'});
watch({ element: ..., callback: ... })

Listen for a specific event, and annotate the message with custom data. For example:

// register a click handler that snakes some data from the DOM and specifies the the event type.
// this wont bubble to the wrapper element being watched.{
  element: document.getElementById('search_button'),
  callback: function(e) {
    e.set('element_value', document.getElementById('search_term').value);
    e.set('event_type', 'search');


Start up the node listener and write events to a log file:

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

Usage Options

$ bin/lilbro --help

Usage: node lilbro [options]

Options: --png-bug FILE path to the image file to return to clients --https-port PORT port to listen for https connections --https-key FILE path to the file containing the private key --https-cert FILE path to the file containing the secure certificate --http-port PORT port to listen on --devent-host HOST devent hostname --devent-port PORT devent port --devent-topic STRING devent topic to write events to when writing to devent --client-js-path DIR path to find client library sources --writer [file|devent-zmq|devent-forwarder] method to use for writing events --output-file FILE path to log to when writing events to file


To write to Devent, use

--writer devent-zmq
--writer devent-forwarder
. See devent-router and devent-forwarder.

Event Context


When a click happens, we gather what context we can and send that along with the event. If the target element has an

and/or a
, we note that. Otherwise, we traverse up the DOM until we find a parent’s
. 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 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

cookie, and a short-lived
cookie. We send the values of these cookies along so that we can string events together and aggregate later.

Event Schemas

To create the smallest request possible when writing events, Lil Brother de-couples the key-value pairs into a SOH-delimited list comprised of the values in the order specified in the schema's

. These values are sent to the server via an image request, which re-assembles the list back into key-value pairs and forwards the data to a backend writer. Both the client code and server code require access to a schema file which allows them to disassemble the data and re-assemble them in the correct order.

Lil Brother comes with a default schema which includes attributes for context around the click and context around the visit and visitor and their browser.

To create additional or multiple schemas, add them under

with the naming scheme
, and then load the client library with a query string parameter that refers to that version with


This library was developed by Douglas Hunter, Dave Kozma and Eric Smiling at Shutterstock


MIT © 2012-2017 Shutterstock Images, LLC

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.