Snoopy
Front-end tracking library for asynchronously sending browser events to an external tracker URL with plugins.
Usage
Include snoopy with:
import Snoopy from 'snoopy';
API
Snoopy(name, trackerURL, options = {})
Instantiates a snoopy object for tracking front end events and sending to a tracker URL
Arguments
- name (string): name of Snoopy tracker instance
- trackerURL (string): URL to send tracking data to
- options (object): object containing Snoopy options (e.g. headers, request method, disabledPlugins)
Options
- disabledPlugins (object): Names of plugins to be disabled, accepts a k:v object with:
{ 'nameOfPlugin': true, 'plugin2': true, ...}
- method (string): HTTP request method (will use 'POST' if not provided)
- headers (object): HTTP headers to include. Will not include any by default
Returns
- Snoopy (object)
Example
var snoopy = 'tracker' 'mytrackerurl.com';
track(eventName, eventCategory, eventAction, eventOrigin, eventLabel = '', eventValue = '', eventSchema = 'latest', data = {})
Sends event name, payload, and schema to the tracker URL
Arguments
Required
- eventName (string) - Name of the event being tracked
- eventCategory (string) - Category of the event being tracked
- eventAction (string) - Action being performed in the event
- eventOrigin (string) - Origin from which event is being tracked
Optional
- eventLabel (string) - Label associated with the event being tracked
- eventValue (string) - Value associated with the event
- eventSchema (string) - (Default: 'latest'): Schema version for downstream validation
- data (object): Object containing event data
Returns
Promise(Array[eventObject, XMLHttpRequest.xhr])
snoopy// => {eventTimestamp: 1520541978172, eventUuid: "5dc45625-281e-4bd5-ac4b-c625e04f4ceb", eventName: "clickButton", …}
This will send an object to mytrackerurl.com
logging that visitor abc123
did a clickSignup
event, along with a timestamp and any other global parameters you have set.
Notes:
It is highly recommended that you add an eventSchema
, eventLabel
and eventValue
to each event, this will allow GA to pick these events up as well as the internal tracker you are using, and ensure you are sending valid event schemas.
Read here to understand more about GA Events.
set({ k: v })
Add common payload values to all events emitted by the tracker. This will automatically add them to the payload and overwrite previous values if they already existed.
Arguments
- (Object) - obj of key-values including any values you want to set. Can be nested.
Returns
- (Error) - if the argument isn't an object
- (Boolean) - True if success; Never False;
snoopy// => true
unset(stringPath)
Remove payload values added with set()
. Takes a string path delimited by .
and removes node from object, including child nodes.
Arguments
- (String) - Path of key to be deleted, delimited by
.
(key1.key2.key3
would removekey3
and all its children)
Returns
- (Boolean) - True if success; Never False;
snoopy// => true
Plugins
Snoopy is an extensible front-end library. Plugins are loaded automatically from the plugins directory inside of src
, and are used to transform the event object in a sequence. Adding a plugin requires a pull-request.
Example
./plugins/cookies.js
{ thistracker = tracker; thiscookies = this; thisorder = 'after'; return this; } { const pairs = documentcookie; const cookies = {}; for let i = 0; i < pairslength; i += 1 const pair = pairsi; cookiespair0 = ; return cookies; } { eventdatacookies = cookies: thiscookies ; return event; } ;
This will be loaded into Snoopy by default
var snoopy = 'tracker' 'mytrackerurl.com'; snoopy;
Disabling Plugins
var snoopy = 'tracker' 'mytrackerurl.com' disabledPlugins: cookies: true ; snoopy;
Plugin order
Plugins can include an "order" property with a value of either 'before' or 'after'. Plugins without a valid 'order' will be treated as 'before'.
Plugins tagged 'before' will execute before those marked 'after', thus those marked 'after' can refer to those marked 'before'.
Development
Getting started
- Clone the library then
- Run
yarn install
(recommended)
- Development mode
- Running
npm start
will open a webpack dev server
- Running the tests
- Run
yarn test
oryarn test:watch
Scripts
yarn build
ornpm run build
- produces production version of your library under thelib
folderyarn test
oryarn test:watch
- well ... it runs the tests :)npm start
- Open a dev server where you can play around with Snoopy