Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/shutterstock/lil-brother
Track clicks and other client-side events on web pages
https://github.com/shutterstock/lil-brother
clicks lil-brother tracker
Last synced: 3 months ago
JSON representation
Track clicks and other client-side events on web pages
- Host: GitHub
- URL: https://github.com/shutterstock/lil-brother
- Owner: shutterstock
- License: mit
- Created: 2012-03-09T12:01:14.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2017-11-20T16:14:10.000Z (almost 7 years ago)
- Last Synced: 2024-07-28T16:48:26.893Z (3 months ago)
- Topics: clicks, lil-brother, tracker
- Language: JavaScript
- Homepage:
- Size: 123 KB
- Stars: 225
- Watchers: 56
- Forks: 39
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Li'l Brother
Li'l Brother tracks clicks on web pages, without blocking any interaction.
## Client
Include the library:
```
```
Listen for clicks on the body:
```javascript
var lilBro = new LilBro({
element: document.body,
server: 'server:8000',
ssl_server: 'server:8443',
track_focus: true
});
```
### LilBro Options
##### element
Reference to top-level container element to monitor for events.
##### server
Server to communicate with over HTTP calls.
##### server_ssl
Server to communicate with over HTTPS calls.
##### visit_id_cookie, visitor_id_cookie
Custom cookie names for visit and visitor cookies. Defaults to `visit_id` and `visitor_id`.
##### watch_focus
If set to true, will log focus/blur events that occur.
##### event_base
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:
```javascript
lilBro.write({event_type: 'page_load'});
```
##### watch({ element: ..., callback: ... })
Listen for a specific event, and annotate the message with custom data. For example:
```javascript
// 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.
lilBro.watch({
element: document.getElementById('search_button'),
callback: function(e) {
e.set('element_value', document.getElementById('search_term').value);
e.set('event_type', 'search');
}
});
```
## Server
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
```
#### Devent
To write to Devent, use `--writer devent-zmq` or `--writer devent-forwarder`. See [devent-router](https://github.com/shutterstock/devent-router) and [devent-forwarder](https://github.com/shutterstock/devent-forwarder).
## Event Context
#### Clicks
When a click happens, we gather what context we can and send that along with the event. 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 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.
## 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 `key_map`. 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](client/src/LilBro.Schema.js) 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 `client/src` with the naming scheme `LilBro.Schema.__VERSION__.js`, and then load the client library with a query string parameter that refers to that version with `?v=__VERSION__`.
## Authors
This library was developed by Douglas Hunter, Dave Kozma and Eric Smiling at [Shutterstock](http://www.shutterstock.com)
## License
[MIT](LICENSE) © 2012-2017 Shutterstock Images, LLC