@newfold/js-utility-ui-analytics

Welcome to the UI Analytics Package

A package for tracking analytics events in WordPress React User Interfaces.

Installation

Install the package

npm install @newfold/js-utility-ui-analytics

Usage

Hiive Analytics

Initialize the HiiveAnalytics module. Refer the initialize API documentation for more information.

import { HiiveAnalytics } from '@newfold/js-utility-ui-analytics';
HiiveAnalytics.initialize( {
     namespace,
     urls: {
          single,
          batch,
     },
     settings: {
          debounce: {
               time,
          },
          queue: {
               threshold
          },
     },
} );

Once the HiiveAnalytics module has been initialized, you can track events in your React components/pages.

Sending an event

To send an event to the default API:

import { HiiveAnalytics, HiiveEvent } from '@newfold/js-utility-ui-analytics';

const hiiveEvent = new HiiveEvent( 'module', 'click', 'some-data', 'namespace');

// Reports the event to urls.single defined during initialization.
HiiveAnalytics.send( hiiveEvent );

Batching and Dispatching events

To queue an analytics event:

import { HiiveAnalytics, HiiveEvent } from '@newfold/js-utility-ui-analytics';

// category, action, data
const hiiveEvent1 = new HiiveEvent( 'module', 'click', 'some-data', 'namespace-1');
const hiiveEvent2 = new HiiveEvent( 'module', 'click', {
     value: 'object of data'
}, 'namespace-2');

HiiveAnalytics.track( hiiveEvent1 );
HiiveAnalytics.track( hiiveEvent2 );

The above code snippet tracks HiiveEvent objects in a Redux store queue and does not report them to the API immediately, to report all the queued events to a batch API:

import { HiiveAnalytics } from '@newfold/js-utility-ui-analytics';

// Reports all the queued events in a namespace to urls.batch defined during initialization.
HiiveAnalytics.dispatchEvents( 'namespace' );

Note: This sends the entire queue of events to the batch API as an array, your batch API should be built to handle an array of HiiveEvent's.

Adding a Debounce

If you pass a value for settings.debounce.time as per the initialize API documentation, a debounce gets setup automatically for you. The debounce interval must pass once an event has been tracked after which dispatchEvents gets called automatically to report all the events in the queue.

This is useful when you want to

1. track a short burst of events. Ex: rapid clicks/user inputs. Debouncing will allow you to wait for the user input to complete and then call the API.
2. report analytics at a regular interval instead of calling HiiveAnalytics.dispatchEvents( 'namespace' ) every time you track events.
3. prevent the queue from getting too big. Debouncing will periodically dispatchEvents and clear the queue.

If you wish to disable the debounce, use:

import { HiiveAnalytics } from '@newfold/js-utility-ui-analytics';

// Disables the debounce in a given namespace.
HiiveAnalytics.disableDebounce( 'namespace' );

Modifying the Threshold

By default, if the number of events tracked in the queue crosses a number of 100, HiiveAnalytics.dispatchEvents gets called automatically for you. If you want to modify this threshold you can pass a value to settings.queue.threshold as per the initialize API documentation.

API

HiiveAnalytics

initialized

Determines whether Hiive analytics have been initialized or not.

Returns boolean whether Hiive analytics have been initialized or not.

validate

Validates that the parameter is an instance of HiiveEvent.

Parameters

• event Object Any valid JS Object.

Returns boolean whether the param is a valid HiiveEvent instance or not.

initialize

Initializes the HiiveAnalytics module for sending out Hiive analytics events.

Parameters

• param Object Data to initialize Hiive analytics.

  • namespace string The namespace to be initialized. Events, URL's, settings.... are associated with a namespace in which they are tracked. Each namespace operates independent of other namespaces.

  • urls Object Contains URL's to report analytics.

    • single string The URL that can handle a single event.
    • batch string The URL that can handle an array of events.

  • settings Object Settings that define the behavior of HiiveAnalytics.

    • debounce Object Settings related to the debounce.

      • time number The interval that must pass once an event has been tracked after which a batch request gets placed automatically to the batch URL.

    • queue Object Settings related to the Hiive events queue.

      • threshold number The limit that the number of events in the queue must cross after which a batch request gets placed automatically to the batch URL.

Returns boolean Whether the module was initialized or not.

track

Tracks the event by putting it in a queue.

Parameters

• event HiiveEvent The event object to track.

Returns boolean whether the event has been successfully queued for tracking or not.

send

Reports the event to urls.single defined during initialization.

Parameters

• event HiiveEvent The event object to send.

Returns Promise<boolean> whether the event has been successfully sent or not.

dispatchEvents

Reports all the queued events in the given namespace to urls.batch defined during initialization.

Parameters

• namespace string The namespace in which the queued events need to be dispatched.

Returns Promise<boolean> whether or not all the events were sent to the batchUrl successfully.

resetDebounceInstance

Resets the debounce instance countdown.

Parameters

• namespace string The namespace in which the debounce needs to be reset.

Returns boolean whether the reset occurred successfully or not.

disableDebounce

Disables the debounce.

Parameters

• namespace string The namespace in which the debounce should be disabled.

Returns boolean whether the debounce has been successfully disabled or not.

HiiveEvent

Defines the structure of a Hiive analytics event.

1. category The category of the event (This actual value will depend on the URL you are reporting to).
2. action The action that triggered the event (The actual value will depend on the URL you are reporting to).
3. data Data related to the event.
4. namespace A valid, initialized namespace that the event must be tracked in.

Local Development

To setup this package for local development/testing:

Clone the Github repository

git clone [e-mail]:newfold/js-utility-ui-analytics.git

Install the locally cloned package in your project

npm install <path_to_your_cloned_directory>

Contributing

If you want to add new analysis platforms to this library, please follow the same structure used in building the Hiive analytics platform. This helps us keep the code organized when dealing with platform specific requirements.