Include UserAle.js in your project
To include UserAle.js in your project with default configuration, simply include the script tag below:
<script src="https://draperlaboratory.github.io/useralejs/useralejs.min.js"></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 https://github.com/draperlaboratory/useralejs.git
npm install
npm run build
To run tests and linting:
npm test
npm run test:watch
See package.json for full script options.
Configuration
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 Parameter | Default | Description |
|---|---|---|
data-url | http://localhost:8000 | The URL to which logs will be sent |
data-autostart | true | Should UserAle.js start automatically on page load |
data-interval | 5000 | The minimum time interval in ms between batch transmission of logs |
data-threshold | 5 | The minimum number of logs to be sent in a batch |
data-user | null | Identifier for the particular user of the application |
data-version | null | The application version |
data-log-details | false | Should detailed logs (key strokes, input/change values) be recorded |
data-resolution | 500 | Delay in ms between instances of high frequency logs like mouseovers, scrolls, etc. |
data-user-from-params | false | Should the user field (as in |
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.
- Follow the instructions for downloading Distill as you would normally.
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
- 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).
- 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: