This is an automated email from the ASF dual-hosted git repository.
poorejc pushed a commit to branch FLAGON-469
in repository https://gitbox.apache.org/repos/asf/incubator-flagon-useralejs.git
The following commit(s) were added to refs/heads/FLAGON-469 by this push:
new 7dc553d [FLAGON-481] Updated top level readme--substantially improved
7dc553d is described below
commit 7dc553d1e84ed5b9add4bfc1dd8a7f2497c3c76a
Author: poorejc <[email protected]>
AuthorDate: Sat Jan 25 23:37:52 2020 -0500
[FLAGON-481] Updated top level readme--substantially improved
---
README.md | 279 +++++++++++++++++++++++----------
example/webpackUserAleExample/index.js | 1 +
2 files changed, 201 insertions(+), 79 deletions(-)
diff --git a/README.md b/README.md
index 138f788..19ea9c9 100755
--- a/README.md
+++ b/README.md
@@ -6,11 +6,21 @@
[](http://www.apache.org/licenses/LICENSE-2.0)
-The official JavaScript client for [Apache Flagon
UserALE](https://github.com/apache/incubator-flagon-userale).
+Apache UserALE.js is part of the [Apache Flagon
Project](http://flagon.incubator.apache.org/). It is a client side
instrumentation library written in JavaScript designed for easy deployment and
lightweight configuration in gathering logs from your web applications for
behavioral analytics use-cases.
-UserALE.js is a client side instrumentation library written in JavaScript. It
is designed to be an easy-to-use, lightweight, and dependency-free way to
quickly gather logs from your web applications.
+Once included in your project, Apache UserALE.js provides comprehensive
logging capabilities capturing every event on every element rendered in your
DOM.
-Additional documentation can be found at our [project
website](http://flagon.incubator.apache.org/userale/).
+Additional documentation and a demonstration can be found at the [Apache
Flagon website](http://flagon.incubator.apache.org/userale/).
+
+### Table of Contents
+[What's New in the Current
Version](https://github.com/apache/incubator-flagon-useralejs#whats-new-in-version-202)
+[Installation](https://github.com/apache/incubator-flagon-useralejs#installation)
+[Configure](https://github.com/apache/incubator-flagon-useralejs#configure)
+[Usage](https://github.com/apache/incubator-flagon-useralejs#usage)
+[Examples](https://github.com/apache/incubator-flagon-useralejs#examples)
+[Modifying
Source](https://github.com/apache/incubator-flagon-useralejs#modifying-source)
+[Contributing](https://github.com/apache/incubator-flagon-useralejs#contributing)
+[License](https://github.com/apache/incubator-flagon-useralejs#license)
## What's New in Version 2.0.2?
@@ -20,68 +30,86 @@ Additional documentation can be found at our [project
website](http://flagon.inc
See our
[CHANGELOG](https://github.com/apache/incubator-flagon-useralejs/blob/master/CHANGELOG.md)
for a complete list of changes.
-## Prerequsites
+## Installation
-To build UserALE.js, you will need to download our source (here), our [release
distributions](http://flagon.incubator.apache.org/releases/) or include in your
project via the [flagon-userale NPM
module](https://www.npmjs.com/package/flagon-userale).
+Either through cloning our [source
repo](https://github.com/apache/incubator-flagon-useralejs) or by using npm:
-UserALE.js utilizes NPM for package and dependency management. Execute the
following to install dependencies.
-```
-#install required packages
-npm install
-
-#review major dependencies
-npm ls --depth=0
+```html
+npm install flagon-userale
```
-Pre-tested and pre-built UserALE.js script are included in the [/build
dir](https://github.com/apache/incubator-flagon-useralejs/tree/master/build) in
our repositories, release artifiacts, and our [NPM
module](https://www.npmjs.com/package/flagon-userale). However, you can modify
and build your own versions of these scripts with the following steps:
+To include UserALE.js in your project, include as a `module`:
-## Build
+```html
+import * as userale from 'flagon-userale';
-To build UserALE.js:
+or
-```
-#Build UserALE.js
-npm run build
+const userale = require('flagon-userale');
```
-## Test
+You can also include UserALE.js as a `script-tag`. A pre-built version of the
userale script is included in our package and
+repositories:
-To test UserALE.js:
-```
-#Run UserALE.js unit tests
-npm run test
-```
-... you'll see something like:
+```html
+<script
src="./node_modules/flagon-userale/build/userale-2.1.0.min.js"></script>
```
-...
- attachHandlers
- ✓ attaches all the event handlers without duplicates
- ✓ debounces bufferedEvents (505ms)
- defineDetails
- - configures high detail events correctly
-...
- 45 passing (954ms)
- 1 pending
+If you include UserALE.js as a `script-tag`, consider installing via npm as a
development dependency, instead:
+
+```html
+npm install --save-dev flagon-userale
```
-Any failing tests will also be logged in the terminal. If there are failing
tests, please consider [logging an issue in
JIRA](https://issues.apache.org/jira/projects/FLAGON).
-## Use and Configure
+We also support a
[WebExtension](https://github.com/apache/incubator-flagon-useralejs/tree/master/src/UserALEWebExtension)
that can be added to your browser in developer mode. Follow the link for
instructions.
+
+## Configure
-To start logging with UserALE.js, you can either include our script in the web
application to be logged, or use our
[WebExtension](https://github.com/apache/incubator-flagon-useralejs/tree/master/src/UserALEWebExtension)
to gather logs across any page a user visits.
+Some configuration is necessary. At minimum you will need to provide
UserALE.js an end-point to ship logs to; default behavior is to ship logs to
`localhost:8000/`.
-To collect logs from a specific project, simply include this script tag on the
page:
+If you have included UserALE.js in your project as a `module`, you will need
to use our 'userale.options' function, which exposes library configuration
options through our API:
```html
-<script src="/path/to/userale-2.0.2.min.js"></script>
+const changeMe = "me";
+userale.options({
+ "userId": changeMe,
+ "url": "http://localhost:8000/";,
+ "version": "next",
+ "logDetails": false,
+ "sessionID": "this one"
+});
```
-UserALE.js is designed to be easily configured to fit your use case. We use
HTML data parameters to pass configuration options to the library. For example,
to set the logging URL:
+
+The complete list of configurable parameters that can be configured via
'userale.options' is:
+
+| Param | Description | Default |
+|---|---|---|
+| url | Logging URL | http://localhost:8000 |
+| autostart | Should UserALE.js start on page load | true |
+| transmitInterval | Delay between transmit checks | 5000 (ms) |
+| logCountThreshold | Minimum number of logs to send | 5 |
+| userId | User identifier | null |
+| sessionID | Session identifier | null |
+| version | Application version identifier | null |
+| logDetails | Toggle detailed logs (keys pressed and input/change values) |
false |
+| resolution | Delay between instances of high frequency logs (mouseover,
scroll, etc.) | 500 (ms) |
+| userFromParams | Query param in the page URL to fetch userId from | null |
+| toolName | Name of tool being logged | null |
+| authHeader | Authorization header to be passed to logging endpoint | null |
+
+If you have included UserALE.js as a `script-tag` in your project, you can use
HTML data parameters to pass configuration options to the library through the
script tag. For example:
```html
-<script src="/path/to/userale-2.0.2.min.js"
data-url="http://yourLoggingUrl";></script>
+ <script
+ src="./node_modules/flagon-userale/build/userale-2.1.0.min.js"
+ data-url="http://localhost:8000/";
+ data-user="example-user"
+ data-version="2.1.0"
+ data-tool="Apache UserALE.js Example"
+ ></script>
```
-The complete list of configurable options is:
+You have access to the same parameters listed above, however, naming
conventions vary slightly for use in HTML:
| Param | Description | Default |
|---|---|---|
@@ -95,48 +123,63 @@ The complete list of configurable options is:
| data-resolution | Delay between instances of high frequency logs (mouseover,
scroll, etc.) | 500 (ms) |
| data-user-from-params | Query param in the page URL to fetch userId from |
null |
| data-tool | Name of tool being logged | null |
+| data-auth | Authorization header to be passed to logging endpoint | null |
+
+If you are using our
[WebExtension](https://github.com/apache/incubator-flagon-useralejs/tree/master/src/UserALEWebExtension),
+you can modify some of these parameters via the extensions' 'options' page.
+
+
+To build UserALE.js, you will need to download our source (here), our [release
distributions](http://flagon.incubator.apache.org/releases/) or include in your
project via the [flagon-userale NPM
module](https://www.npmjs.com/package/flagon-userale).
+
+## Usage
+
+Including UserALE.js in your project as a `module` attaches the UserALE.js
script as an object to the page.
-If you're interested in using our WebExtension to log user activity across all
pages they visit, check out our browser specific instructions
[here](https://github.com/apache/incubator-flagon-useralejs/tree/master/src/UserALEWebExtension).
+We have exposed a number of functions that assist you in modifying, filtering,
and customizing logs
-You can also test out UserALE.js behavior with different script tag parameters
using our ['example' test
utility](https://github.com/apache/incubator-flagon-useralejs/tree/master/example).
+A complete list of available functions are as follows:
-## Customizing your logs
+| Function | Description | Notes |
+|---|---|---|
+| userale.options | modify userale's configuration option | see top level
README for complete list of options |
+| userale.filter | filters out logs from logging queue by keys or values |
filters are callbacks with global scope |
+| userale.map | modify/add log keys or values | mappings are callbacks with
global scope |
+| userale.log | appends a custom log to the log queue | the custom log object
is an object key:value pairs |
+| userale.packageLog | transforms the provided event into a log and appends it
to the log queue | designed for HTML events |
+| userale.packageCustomLog | packages the provided customLog to include
standard meta data and appends it to the log queue | designed for non HTML
events|
+| userale.details | defines the way information is extracted from various
events | supports packageLog/packageCustomLog 'details' |
+| userale.getSelector | builds a string CSS selector from the provided HTML
element id | populates 'target' field in packaged logs |
+| userale.buildPath| builds an array of elements from the provided event
target, to the root element (DOM path) | populates the 'path' field in packaged
logs |
+| userale.start | used to start the logging process if | unecessary if
'autostart' is set to true in initial setting (default) |
+| userale.stop | halts the logging process. Logs will no longer be sent | will
need to invoke userale.start to restart logging |
+
+Including UserALE.js as a `script-tag` provides you access to the same
functions listed above. However, UserALE.js essentially
+becomes a property of the DOM. As such, you'll need to call functions as a
window property:
-For some applications, it may be desirable to filter logs based on some
runtime parameters or to enhance the logs with information available to the
app. To support this use-case, there is an API exposed against the global
UserALE object.
+```html
+userale.options = window.userale.options
+```
-The [flagon-useralejs NPM
module](https://www.npmjs.com/package/flagon-userale) exposes UserALE.js
functions for use in the NPM environment. However, this API is a cleaner, more
intuitive way of modifying UserALE.js behavior to suite your needs.
+## Examples
-The two functions exposed are the `setLogFilter` and `setLogMapper` functions.
These allow dynamic modifications to the logs at runtime, but before they are
shipped to the server.
+We provide a number of examples to illustrate how the [functions
above](https://github.com/apache/incubator-flagon-useralejs#usage) can be used
with sample webpages and logging servers. These are tailed for [module
examples](https://github.com/apache/incubator-flagon-useralejs/tree/master/example/webpackUserAleExample)
+and [script-tag
examples](https://github.com/apache/incubator-flagon-useralejs/tree/master/example).
+Select examples are below:
+
+Filter your logs with `userale.filter`:
-Here is an example of a filter that bounces out unwanted log and event types
from your logging stream:
```html
-<html>
- <head>
- <script src="/path/to/userale-2.0.2.min.js"
data-url="http://yourLoggingUrl";></script>
-<!--
-Modify the array page-by-page to curate your log stream:
-by adding unwanted event 'types' in type_array;
-by adding unwanted log classes to eliminate 'raw' or 'interval' logs from your
stream.
--->
- <script type="text/javascript">
- var type_array = ['mouseup', 'mouseover', 'dblclick', 'blur', 'focus']
- var logType_array = ['interval']
- window.userale.filter(function (log) {
- return !type_array.includes(log.type) &&
!logType_array.includes(log.logType);
- });
- </script>
- <body>
- <div id="app">
- <!-- application goes here -->
- </div>
- </body>
-</html>
-```
-
-Here is an example of a mapping function that adds customizable labels to
events detected on specific DOM elements:
+userale.filter(function (log) {
+ var type_array = ['mouseup', 'mouseover', 'mousedown', 'keydown',
'dblclick', 'blur', 'focus', 'input', 'wheel'];
+ var logType_array = ['interval'];
+ return !type_array.includes(log.type) &&
!logType_array.includes(log.logType);
+});
+```
+
+Modify (add/remove) log fields with surgical precision using `userale.map`:
+
```html
- <script type="text/javascript">
- window.userale.map(function (log) {
+userale.map(function (log) {
var targetsForLabels = ["button#test_button"];
if (targetsForLabels.includes(log.target)) {
return Object.assign({}, log, { CustomLabel: "Click me!" });
@@ -144,16 +187,94 @@ Here is an example of a mapping function that adds
customizable labels to events
return log;
}
});
- </script>
```
-Even with this small API, it is possible to compose very powerful logging
capabilities and progressively append additionally app-specific logic to your
logs.
+Generate custom logs with `userale.log`:
+
+```html
+document.addEventListener('change', function(e) {
+ if (e.target.value === 'log') {
+ userale.log({
+ target: userale.getSelector(e.target),
+ path: userale.buildPath(e),
+ type: e.type,
+ logType: 'custom',
+ userAction: false,
+ details: 'I can make this log look like anything I want',
+ customField1: 'foo',
+ customField2: 'bar',
+ userId: userale.options().userId,
+ toolVersion: userale.options().version,
+ toolName: userale.options().toolName,
+ useraleVersion: userale.options().useraleVersion,
+ sessionID: userale.options().sessionID,
+ customLabel: "(custom) Log Example"
+ });
+ }
+});
+```
+
+User our own log packaging pipeline to streamline custom HTML event logging
with `userale.packageLog`:
+
+```html
+document.addEventListener('change', function(e){
+ if (e.target.value === 'packageLog') {
+ /**You can then use the 'Mapping' API function to modify custom logs
created with the packageLog function*/
+ userale.map(function (log) {
+ var targetsForLabels = ['change'];
+ if (targetsForLabels.includes(log.type)) {
+ return Object.assign({}, log, { logType: 'custom',
customLabel: 'packageLog Example' });
+ } else {
+ return log;
+ }
+ });
+ /**You can also use the details function to package additional log
meta data, or add custom details*/
+ userale.packageLog(e, userale.details(userale.options(),'change'));
+ } else {
+ return false
+ }
+});
+```
+
+Again, see [Usage](https://github.com/apache/incubator-flagon-useralejs#usage)
for differences in invoking these functions with `module` and `script-tag`
includes.
+
+You can find additional examples on our
[website](http://flagon.incubator.apache.org/docs/useralejs/API/).
+
+## Modifying Source
+
+You may wish to modify UserALE.js to suite your needs. After making
modification to [UserALE.js
src](https://github.com/apache/incubator-flagon-useralejs/tree/master/src),
+you will need to rebuild the UserALE.js script (and run tests).
+
+To (re)build UserALE.js:
+
+```
+npm run build
+```
+
+To run UserALE.js unit tests:
+```
+npm run test
+```
+
+We use gulp-mocha for unit tests. The results will print to your terminal:
+```
+...
+ attachHandlers
+ ✓ attaches all the event handlers without duplicates
+ ✓ debounces bufferedEvents (505ms)
+ defineDetails
+ - configures high detail events correctly
+...
+
+ 45 passing (954ms)
+ 1 pending
+```
+Any failing tests will also be logged in the terminal. If there are failing
tests, please consider [authoring an issue in
GitHub](https://github.com/apache/incubator-flagon-useralejs/projects/1).
-You can experiment with these functions in our [example test
utility](https://github.com/apache/incubator-flagon-useralejs/tree/master/example).
## Contributing
-Contributions are welcome! Simply [submit an issue
report](https://issues.apache.org/jira/browse/FLAGON) 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. If you want to
become a contributor to the project, see our [contribution
guide](http://flagon.incubator.apache.org/docs/contributing/).
+Contributions are welcome! Simply [submit an issue
report](https://github.com/apache/incubator-flagon-useralejs/projects/1) 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. If you
want to become a contributor to the project, see our [contribution
guide](http://flagon.incubator.apache.org/docs/contributing/).
Join the conversation: tell us your needs, wishes, and interests by joining
our [mailing list]([email protected])!
diff --git a/example/webpackUserAleExample/index.js
b/example/webpackUserAleExample/index.js
index 4f9b6a1..17f61cd 100644
--- a/example/webpackUserAleExample/index.js
+++ b/example/webpackUserAleExample/index.js
@@ -25,6 +25,7 @@ import * as userale from 'flagon-userale';
const changeMe = "me";
userale.options({
"userId": changeMe,
+ "url": "http://localhost:8000/";,
"version": "next",
"logDetails": false,
"sessionID": "this one"
