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 = new 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.track('clickButton', 'myCategory', 'myAction', 'myOrigin', 'myLabel', 'myValue', 'latest', {user_id: '123456'})
// => {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.set({ 'user_id': '123456', 'source': 'referral' })
// => 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 remove key3 and all its children)

Returns

• (Boolean) - True if success; Never False;

snoopy.unset('user.account.userId')
// => 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

class Cookies {
  constructor(tracker) {
    this.tracker = tracker;
    this.cookies = this.getCookies();
    this.order = 'after';
    return this;
  }

  getCookies() {
    const pairs = document.cookie.split(';');
    const cookies = {};
    for (let i = 0; i < pairs.length; i += 1) {
      const pair = pairs[i].split('=');
      cookies[(pair[0]).trim()] = decodeURIComponent(pair[1]);
    }
    return cookies;
  }

  callback(event) {
    event.data.cookies = {
      cookies: this.cookies,
    };
    return event;
  }
}

export default Cookies;

This will be loaded into Snoopy by default

var snoopy = new Snoopy('tracker', 'mytrackerurl.com');

snoopy.track('clickButton', 'myCategory', 'myAction', 'myOrigin', 'myLabel', 'myValue', 'latest', {user_id: '123456'}).then(function(response) {
	console.log(response[0].payload.cookies);
	// => (String) of all your non http-only cookies
});

Disabling Plugins

var snoopy = new Snoopy('tracker', 'mytrackerurl.com', { disabledPlugins: { cookies: true } });

snoopy.track('clickButton', 'myCategory', 'myAction', 'myOrigin', 'myLabel', 'myValue', 'latest', {user_id: '123456'}).then(function(response) {
	console.log(response[0].payload.cookies);
	// => undefined
});

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

1. Clone the library then

• Run yarn install (recommended)

2. Development mode

• Running npm start will open a webpack dev server

3. Running the tests

• Run yarn test or yarn test:watch

Scripts

• yarn build or npm run build - produces production version of your library under the lib folder
• yarn test or yarn test:watch - well ... it runs the tests :)
• npm start - Open a dev server where you can play around with Snoopy