Studiokit-caliper-js NPM

studiokit-caliper-js

studiokit-caliper-js is a common library of services for implementing applications with the caliper-js Javascript client for IMS Global Caliper Analytics (an implementation of the Caliper SensorAPI™).

studiokit-caliper-js current supports Caliper v1.0

Features

Persistent Queue: Events and Entities are saved to a queue that is persisted to localStorage, or another storage method of your choice.
Convenience Methods: Easily start and end Sessions with simplified methods.
Session Keep-Alive: The current Session's dateModified is periodically updated and sent to the EventStore to track Session activity before it is ended.
Session Timeout: Sessions are ended automatically (timed out) when the user is idle (no mouse, touch, keyboard, scroll events) or away from the app for longer than the sessionTimeoutThreshold.

Installation

npm install --save studiokit-caliper-js

Implementation

With Node

const StudioKit = require('studiokit-caliper-js');
// or
import StudioKit from 'studiokit-caliper-js';

const options = {...}; // see below
const caliperService = new StudioKit.CaliperService(options);

Without Node

npm run build

This will create a browserified file in the dist folder. Add this script to your HTML file like <script src="dist/studiokit-caliper.js"></script>. You can then access the JavaScript global parameter StudioKit.

Options

name	required	type	description	default value
sensorId	true	string	The caliper-js Sensor Id
sensorOptions	true	Object	The caliper-js Sensor Options see the node https docs
appId	true	string (IRI)	The JSON-LD `@id` of the Caliper SoftwareApplication
appName	true	string	The name of Caliper SoftwareApplication
getToken	true	function	A function that is expected to return a `Promise`, which when complete, returns an OAuth Access Token response containing the following properties: `accessToken`: the OAuth token for the EventStore`expires`: A date string representing when the token expires.
storageService	true	Object	An object (or service) that provides data persistence, acting as a key-value store, e.g. LocalStorage. Must implement the following methods: `function getItem(key)`: return a saved object by key.`function setItem(key, value)`: save an object by key.`function removeItem(key)`: remove an object by key.	An in-memory placeholder, does not actually persist data.
autoSend	false	boolean	Whether or not to send the queue of Caliper events on a timer.	true
sendInterval	false	number (milliseconds)	How often a request containing the current queue of Caliper events is sent, enabled by `autoSend`.	`1000 * 10` // 10 seconds
sessionIriPrefix	false	string	The value with which to prefix all Caliper Session `@id` values. Will be prefixed to form valid IRI, e.g. `${sessionIriPrefix}/session/${uuid}`	`null`, defaults to `appId`
sessionTimeoutThreshold	false	number (milliseconds)	The amount of time a Session can be idle (e.g. no mouse, keyboard, touch, or scroll events) before the Session is ended as `TIMED_OUT`.	`1000 * 60 * 30` // 30 minutes
sessionKeepAliveThreshold	false	number (milliseconds)	How often activity should trigger the Session to be "kept alive" by having its `dateModified` updated, and sent to the EventStore.	`1000 * 60 * 15` // 15 minutes
activityUpdateThreshold	false	number (milliseconds)	How often the activity sent to `onActivity()` (e.g. mouse, keyboard, touch, or scroll events, or manual calls) is processed.	`1000 * 60` // 1 minute
onError	false	function	A function that is called when an error is encountered, e.g. `function(err) {}`	`null`