fastar-logger

FastarLogger

NOTE: A newer version of the logger is available. This package will be removed in the near future.

FastarLogger is a JavaScript library used to record mouse events and events from device sensors (accelerometer, gyroscope). It allows to log pressing and releasing mouse buttons (left, middle, right, forward and back), mouse movements, angular velocity and acceleration of the device along all three axes. For easy and fast integration we recommend to use behalearn - server app as a backend server.

Installation

Using a Downloaded version of FastarLogger

Download	Description
FastarLogger	Beta version of FastarLogger

Inside the archives downloaded from the above link, you will see following files:

• fastar-logger.min.js - This is the minified library JavaScript code.
• fastar-logger.min.js.map - This file maps the minified file to original source code.
• fastar-logger.js - This is the readable, unminified JavaScript library.
• fastar-logger.js.map - This file maps the unminified file to original source code.

Unzip the downloaded archive to your website’s directory and add this to the head of your HTML code:

<script src="/path/to/fastar-logger.js"></script>

Now you can use FastarLogger on your webpage like this:

<script>
  let config = {apiUrl: 'https://your-domain.com'};
  let logger = new fastarLogger.Logger(config);
  logger.init().then(
      () => logger.startLogging()
    );
</script>

Using a JavaScript package manager

If you use the npm package manager, you can fetch a local copy of FastarLogger by running:

npm install fastar-logger

FastarLogger is written using ES2015 modules. To import specific FastarLogger Module into an ES2015 application (Logger in this case):

import {Logger} from "fastar-logger";

Or import everything into a namespace:

import * as fastarLogger from "fastar-logger";

In Node:

var fastarLogger = require("fastar-logger");

Usage

To run logger, you need to create a logger instance with its configuration. You have to define base endpoint URL in the configuration. This endpoint is used to sent recorded data and receive a unique session ID.

You can create logger instance like this:

let logger = new Logger({
    apiUrl: 'https://your-domain.com'
})

You can configure more properties in configuration object. For example you can specify which events you want to be logged. Check documentation for more information.

Now you can initialize new session. When you initialize session, logger will obtain unique session ID. The session ID is part of each recorded log.

logger.init();

To start logging you need to call startLogging() function like this:

logger.startLogging();

To start logging immediately after session is initialized:

logger.init().then(
    () => logger.startLogging()
);

If you want to stop logging data you can simply call stopLogging() function.

logger.stopLogging();

If you want to log custom data you can do it like this:

logger.logCustomEvent({
    action: 'login',
    name: 'John',
})

Data format

Bellow you can see example of mousemove event log:

{
  eventType: 'MOUSE_MOVE',
  payload: {
    mouseButton: 'NO_BUTTON',
    positionX: 1123,
    positionY: 547,
  },
  sessionId: '5c70579af2307d000b7eaf0c',
  sessionStartsAt: 1550866331396,
  time: 7683.980000088923,
};

Documentation

For more information see FastarLogger documentation and API documentation.

Contributing

Features

• Webpack 4 based.
• ES6 as a source.
• Exports in a umd format so the library works everywhere.
• ES6 test setup with Mocha and Chai.
• Linting with ESLint.

Getting started

1. Build library
   • Run npm install to get the project's dependencies
   • Run npm run build to produce minified version of the library.
2. Development mode
   • Having all the dependencies installed run npm run dev. This command will generate an non-minified version of the library and will run a watcher so you get the compilation on file change.
3. Running the tests
   • Run npm run test to run tests

Scripts

• npm run build - produces production version of the library under the lib folder
• npm run dev - produces development version of the library and runs a watcher
• npm run test - runs the tests
• npm run test:watch - same as above but in a watch mode
• npm run demo - runs demo page to show logger in action
• npm run doc - generates JSDoc API documentation

License

Source code is provided under MIT License.