This example provides:

• example usage for UserALE imported as a module into a simple HTML Webpage and built with a package bundler (Webpack);
• a testing utility for developers to evaluate UserALE modifications to logged events;
• a means of viewing log event structure within a simple UserALE logging server;
• a means of testing UserALE API functions within a simple HTML Webpage.

If you are interested in examples for a script tag deployment methodology, see the README in the /examples directory. For details about our web extension, see our UserALE WebExtension documentation.

Ensure that you have node.js installed.

You will need to npm install the flagon-userale npm package.

From ./example/webpackUserAleExample directory, npm install dependencies to run this Example Utility. Note that the UserALE Webpack Example has it's own package.json file, that is separate from the larger flagon-userale package.

Please follow Installation directions if you run into issues.

The Example Page is a simple HTML Webpage with UserALE included as a module import.

The example is pre-built and requires no modification to work.

Open index.html in your browser (you can drag it directly into a tab or double-click it). You will see a very simple HTML Webpage with a few interactive features.

On this page, all user events will be captured and sent to the logging server. See instructions below.

The UserALE Example page works with a simple logging server, which receives log from any UserALE instrumented page or application at localhost:8000.

From the /example directory or its parent directory (not example/webpackUserAleExample) run the following:

$npm run example:watch

Once the server starts you will see:

> flagon-userale@2.1.0 example:watch ...
> nodemon -w ./example example/server.js

[nodemon] 1.19.1
[nodemon] to restart at any time, enter `rs`
[nodemon] watching: ...
[nodemon] starting `node example/server.js`
UserAle Local running on port 8000

The server allows you to watch as logs are sent from the client to the server, as well as review a flat-file of saved logs, which you can view @ /logs in the flagon-userale parent directory.

This means you can test logs from your own instrumented application, the UserALE WebExtension, or the UserALE Example Page, so long as you have not changed the UserALE url configuration option from localhost:8000 (instructions below). This is the default setting for userale; logs generated from module, script tag, or WebExtension deployments will always ship logs to localhost:8000 unless modified via the userale.options (API) configuration, HTML script tag parameter (data-url), or the WebExtension options page.

Start using your instrumented application, browser, or the UserALE Example Page, and you will see logs propagating in the terminal:

[ { target: 'body',
    path: [ 'body', 'html' ],
    clientTime: 1504287557492,
    location: { x: 0, y: 0 },
    type: 'keydown',
    userAction: true,
    details: null,
    userId: 'example-user',
    toolVersion: '2.1.0',
    toolName: 'Apache UserALE Example',
    useraleVersion: '2.1.0' },
 ...
]

Kill the logging script with ^C or as you would any bash script.

Beyond providing you in situ examples of UserALE in action and API usage examples, the test utility is useful for prototyping code blocks for use in your own applications.

Below are a few notes that are useful as you begin to modify the UserALE module imoort example.

• the userale object imports directly into index.js with the following import statement:

import * as userale from 'flagon-userale';

or

const userale = require('flagon-userale');

• index.js is bundled with Webpack, resulting in a main.js file in the /dist directory. index.html includes main.js through a script tag.

<script src="dist/main.js"></script>

• the UserALE module import example is structured like an npm project--it has its own package.json file. This means than any npm commands used for install, built, etc., must be done so within this directory, not its parent directories.

• any modifications of index.js will require that you rebuild main.js, then reload index.html. Run the following within the /example/webpackUserAleExample directory:

$npm run build-example

• UserALE features a robust set of exported functions to support modification and customization of your logs. They can be called as attributes of the userale object (e.g., userale.[function])

• See the top level README for examples and parameters for exports, but a list of exported functions follows:

• additional, annotated examples for most exports can be found embedded within index.js the UserALE module import example.

See the Flagon website for additional documentation on the API and testing for scale.

Contributions are welcome! Simply submit an issue for problems you encounter or submit a pull request for your feature or bug fix. The core team will review it and work with you to incorporate it into UserALE.