@pluralai/spor

spor

• Getting Started
• Usage
• Documentation
  • initialize
  • track
  • getHistory
• Issues

Getting Started

This module is distributed with npm which is bundled with node and should be installed as one of your project's dependencies:

npm install --save @pluralai/spor

or using yarn:

yarn add @pluralai/spor

This library carries no dependencies or peerDependencies allowing it to leave almost no trace on your bundle size.

Usage

To use this library, call Spor.initialize(options) as early as possible after loading the page. This will initialize the library and hook into the environment.

import Spor from '@pluralai/spor';

Spor.initialize();

To track events or inspect the tracking history, use the exported functions. Note that these functions will not perform any actions before you have called Spor.initialize():

import Spor, { TrackingData } from 'spor';

// Construct the tracking data
const data: TrackingData = {
	type: 'TOKEN_SELECTED',
	data: {
		token: 'Aviation Engineering',
		index: 2,
		typed: 'Avi',
	},
	timestamp: new Date(),
};

// Track the event
Spor.track(data);

If you need to inspect the tracking history from the current session, you can get read-only access to the tracking history by invoking the getHistory() function.

import Spor from 'spor';

// Create a connection for a specific user
Spor.initialize({
	user: '8762357',
	environment: 'staging',
});

// Track an event
Spor.track({
	type: 'SOME_EVENT',
	data: {
		message: 'Important event',
		trigger: 'Very important button',
	},
});

const history = Spor.getHistory();

// {
//   user: '8762357',
//   environment: 'staging',
//   data: [
//     {
//       type: 'SOME_EVENT',
//       data: {
//         message: 'Important event',
//         trigger: 'Very important button',
//       },
//     },
//   ],
// }

When a user is done with their interaction and ends their session, the tracking history can be retrieved and stored in using whatever medium you are working with.

To ensure that no tracking information is lost, this could be done by adding a listener on the browsers unload event and then getting the history.

import Spor from 'spor';

window.addEventListener('unload', () => {
	const history = Spor.getHistory();

	// Save to a database of your choice
	saveHistory(history);
});

Documentation

The Spor class implements the SporInterface and exposes a set of functions to initialize, track and store tracking data:

interface SporInterface {
	track: (event: TrackingEvent) => TrackingEvent;
	initialize: (options?: InitializeOptions) => void;
	getHistory: () => TrackingHistory | null;
}

initialize

The initialize function is used to initialize the module and set up the internal history. As seen by the function alias, it takes an optional options object of type InitializeOptions.

interface InitializeOptions {
	[key: string]: unknown;
}

The options is typed with with an index signature allowing you to add whatever information you want to the root of the tracked history. Cannot be changed after the initialization.

The simplest way to initialize the module is to call it without any options:

Spor.initialize();

To attach additional information to the root of the tracking history, for example about the which user performed the action and what environment the event was tracked within, simply pass it to the initialize:

Spor.initialize({
	user: '5201830',
	environment: 'production',
});

// {
// 	 user: '5201830',
// 	 environment: 'production',
// 	 data: [],
// }

track

The track function is used to track an event and add it to the tracking history. The functions accepts an object, which describes the event, as an argument. The event objects type is TrackingEvent which requires a type of event to be set. The type should be a reusable string used to group type of events together. If you need to distinguish between different tracked events, you should add the nested data object with that information.

interface TrackingEvent {
	type: string;
	data?: TrackingEventData;
	timestamp?: string;
}

Apart from requiring an event type, the event object take an optional timestamp and nested data object. The nested data object is of type TrackingEventData which is structured as a index signature with an unknown value, meaning you can store any key-value pair.

The simplest way to track an event is with no associated data, only setting the type:

Spor.track({ type: 'PRODUCT_CLICK' });

If you wanted to attach information about exactly what product was clicked, you can supply that information in the nested data object:

Spor.track({
	type: 'PRODUCT_CLICKED',
	data: {
		name: 'Salmon',
		price: '£12.4',
		quantity: '100g',
	},
	timestamp: 'Fri Aug 09 2019 10:48:55 GMT+0100',
});

getHistory

In case you need access to the sessions tracking history, a snapshot of the data can be read by calling the getHistory function. The history is passed by value and is therefore read-only. If you need to add event to the history, you should use the track method.

const history = Spor.getHistory();

The schema for the history is JSON compliant, making it easy to store and render. As an example, you can imagine a few different events have been tracked during the session. The history is of type TrackingHistory and will look like this:

{
	user: '320340',
	environment: 'production',
	data: [
		{
			type: 'SEARCH_FOCUSED',
			timestamp: 'Fri Aug 02 2019 18:10:58 GMT+0100',
		},
		{
			type: 'TOKEN_SELECTED',
			data: {
				token: 'Aviation Engineering',
				index: 2,
				typed: 'Avi',
			},
			timestamp: 'Fri Aug 02 2019 18:11:28 GMT+0100',
		},
		{
			type: 'TOKEN_SELECTED',
			data: {
				token: 'Turnover',
				index: 0,
				typed: 'Turn',
				range: '£2m+',
			},
			timestamp: 'Fri Aug 02 2019 18:11:34 GMT+0100',
		},
		{
			type: 'SEARCH_EXECUTED',
			timestamp: 'Fri Aug 02 2019 18:11:36 GMT+0100',
		},
		{
			type: 'COMPANY_SELECTED',
			data: {
				companyIdentifier: '3256197',
				index: 5
			},
			timestamp: 'Fri Aug 02 2019 18:11:52 GMT+0100',
		},
	],
}

Issues

If any issues occur using this library, please fill out a detailed bug report on GitHub.

If you want to take a stab at solving the issue yourself, check out the Contributing document on how to get started.