Network Printer Manager

    videoblocks-snoopy

    1.0.13 • Public • Published

    Snoopy

    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)
    1. Development mode
    • Running npm start will open a webpack dev server
    1. 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

    Install

    npm i videoblocks-snoopy

    DownloadsWeekly Downloads

    19

    Version

    1.0.13

    License

    GPL-3.0

    Unpacked Size

    334 kB

    Total Files

    18

    Last publish

    Collaborators

    • videoblocks-dev