Getting Started

Apache UserALE.js is the UserALE client for DOM and JavaScript-based applications. It automatically attaches event handlers, is configurable through HTML5 data parameters or a JS API, and logs every user interaction on a web page, including rich JS single-page apps. You can choose to include UserALE.js directly in your project to track how users engage with it, or if you’re interested in generating logs from any webpage, you can try out our web extension that injects UserALE.js into every webpage.

Note: Work on UserALE.js’ documentation is ongoing. Contributions are welcome. To get involved, see our Contributing guide.

Include UserALE.js in your project

To start logging with Apache UserALE.js, you can include our script directly in your project. More details can be found in our README. You can use our build process to create our script, use a sample in our repos, or pull our scripts from npm.

To include UserALE.js in a specific project, you’ll need to deploy a version of our minified UserALE.js script in an accessible location into your project:

npm install flagon-userale

Include UserALE.js as a module:

import * as userale from 'flagon-userale';

or

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

Our webpack example illustrates this use-case.

Include UserALE.js as a script-tag:

<script src="./node_modules/flagon-userale/build/userale-2.3.0.min.js"></script>

Our script tag example illustrates this use-case

If you include UserALE.js as a script-tag, consider installing via npm as a development dependency:

npm install --save-dev flagon-userale

Include UserALE.js via a CDN:

<script src="https://cdn.jsdelivr.net/npm/flagon-userale@2.1.1/build/userale-2.3.0.min.js"></script>

We also support a WebExtension that can be added to your browser in developer mode. Follow the link for instructions.

Once UserALE.js is installed in your project, your application will start generating logs automatically.

Configure UserALE.js

UserALE.js is designed to be easily configured to fit your use case. In script-tag deployment, use HTML data parameters to pass configuration options to the library.

For example, one thing you’ll need to do is set the URL (location) of your minified UserALE.js script:

<script src="/path/to/userale-2.3.0.min.js" data-url="http://yourLoggingUrl"></script>

The complete list of configurable options is:

NOTE These options are also available through our API, which support deploying UserALE.js as an NPM module.

See our page on Build and Test for UserALE.js to learn how to build your own minified version of the UserALE.js script, or you check-out a pre-built script with default parameters in our repo.

Use our example test utility to experiment with script tag parameters.

Deploying the UserALE.js WebExtension

If you’re interested in using our Web Extension to log user activity across all pages they visit, try our web extension, which injects UserALE.js into any web page your client(s) navigate to. This option is perfect for testing and research. The web extension builds through the same build pipeline as UserALE.js. You can also use pre-built extension files in our repo.

When you’re ready to deploy the UserALE.js web extension, follow the instructions below:

1. Load the web extension into your browser.
   1. Firefox
      1. Open Firefox
      2. Enter about:debugging into the URL bar and press enter
      3. Check the box to ‘Enable add-on debugging’
      4. Press the ‘Load Temporary Add-on’ button
      5. Navigate to the root of the web extension directory (e.g. ‘build/UserAleWebExtension’)
      6. Press Open, and confirm that ‘User ALE Extension’ appears in the list
      7. You may now navigate to a web page to inject the User ALE script!
   2. Chrome
      1. Open Chrome
      2. Enter chrome://extensions into the URL bar and press enter
      3. Check the ‘Developer mode’ box
      4. Press the ‘Load unpacked extension’ button
      5. Navigate to the root of the build directory (e.g. ‘build/UserAleWebExtension’)
      6. Press Ok, and confirm that ‘UserALE Extension’ appears in the list
      7. You may now navigate to a web page to inject the User ALE script!

You can set options for the web extension in your browser by opening the extensions page, finding the extension, and choosing either “Preferences” for Firefox, or “Options” for Chrome.

You can also find more instructions in our README.

Contributing

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