Include UserAle.js in your project

To include UserAle.js in your project with default configuration, simply include the script tag below:

<script src=""></script>

To configure UserAle.js for your application, see Configuration below. Or use the Configuration Builder on our Github page.

Build UserAle.js

To modify and build your own version of UserAle.js, first clone the repo, install dependencies, and make any desired changes. Then build and minify into the build/folder:

git clone 
npm install 
npm run build

To run tests and linting:

npm test 
npm run test:watch

See package.json for full script options.


UserAle.js is configured with HTML5 Data Parameters included in the script tag. For example, to set the URL to send logs to:

<script src="/userale.min.js"data-url="http://localhost:8000/logs"></script>

The full list of options is below:

Data ParameterDefaultDescription
data-urlhttp://localhost:8000The URL to which logs will be sent
data-autostarttrueShould UserAle.js start automatically on page load
data-interval5000The minimum time interval in ms between batch transmission of logs
data-threshold5The minimum number of logs to be sent in a batch
data-usernullIdentifier for the particular user of the application
data-versionnullThe application version
data-log-detailsfalseShould detailed logs (key strokes, input/change values) be recorded
data-resolution500Delay in ms between instances of high frequency logs like mouseovers, scrolls, etc.

Should the user field (as in data-user), be fetched from an "aleuser" URL query parameter if available

Install and Configure Distill

Follow the installation guide here. If you have an existing ElasticSearch instance, the setup will be slightly more involved, but should be as simply as modifying a few existing files.

  1. Follow the instructions for downloading Distill as you would normally.
  2. Modify the docker-compose.yml file at the top-level of the repository. Remove (or comment out using "#") the "elasticsearch" and "kibana" sections. Furthermore, remove the "depends_on" and "links" section in each container that references the "elasticsearch" container. An example of this might be: docker-compose-no-elastic.yaml

  3. Next, modify the "hosts" line in docker/logstash/logstash.conf and specify as either a string or array the address(es) to your Elastic instance(s).
  4. Finally, modify the "ES_HOST" and "ES_PORT" values in distill/config.cfg to whatever your target instance of Elastic is running on.

Enable Cross-Origin Resource Sharing

The logs generated by UserAle is sent to a logging url which is configured in the script tag. Your client may send out failure logs because of a CORS (cross-origin resource sharing) issue. You will need to configure your backend server to enable CORS.

For more information and examples on how to enable CORS on your server, please visit:

  • No labels