You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flagon.apache.org by po...@apache.org on 2019/06/28 19:47:12 UTC
[incubator-flagon] branch master updated: [FLAGON-351] Updated
Website with Flagon name
This is an automated email from the ASF dual-hosted git repository.
poorejc pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-flagon.git
The following commit(s) were added to refs/heads/master by this push:
new e9fb0f5 [FLAGON-351] Updated Website with Flagon name
e9fb0f5 is described below
commit e9fb0f5e533df4e11c73cc8f3b92aebea9dcc938
Author: poorejc <po...@apache.org>
AuthorDate: Fri Jun 28 15:47:04 2019 -0400
[FLAGON-351] Updated Website with Flagon name
---
site/_docs/useralejs/API.md | 23 ++-
site/_docs/useralejs/dataschema.md | 283 ++++++++++++++++++++++++++++++++++++-
site/_docs/useralejs/index.md | 4 +-
site/_docs/useralejs/modifying.md | 27 +++-
4 files changed, 315 insertions(+), 22 deletions(-)
diff --git a/site/_docs/useralejs/API.md b/site/_docs/useralejs/API.md
index 4e6acb5..3c4aa71 100644
--- a/site/_docs/useralejs/API.md
+++ b/site/_docs/useralejs/API.md
@@ -6,9 +6,11 @@ priority: 2
# Modifying UserALE.js Behavior via API
-[Apache UserALE.js](https://github.com/apache/incubator-flagon-useralejs) features a robust API that allows you customize official Apache Flagon UserALE.js [builds](https://github.com/apache/incubator-flagon-useralejs/tree/master/build) page-by-page to suite your needs.
+[Apache UserALE.js](https://github.com/apache/incubator-flagon-useralejs) features a robust API that allows you
+customize official Apache Flagon UserALE.js [builds](https://github.com/apache/incubator-flagon-useralejs/tree/master/build) page-by-page to suite your needs.
-The API exposes two functions: `setLogFilter` & `setLogMapper`. With these two powerful functions, you have a lot of lattitude in customizing and curating your logs.
+The API exposes two functions: `setLogFilter` & `setLogMapper`. With these two powerful functions, you have a lot of
+latitude in customizing and curating your logs.
#API Usage
@@ -41,6 +43,8 @@ This simple array filter pulls mouseover data out of your log stream
```
Here is one UserALE.js filter to rule them all!
+
+
```html
<!--
Modify the array page-by-page to curate your log stream:
@@ -55,9 +59,10 @@ by adding unwanted log classes to eliminate 'raw' or 'interval' logs from your s
});
</script>
```
-You can also use the `setLogFilter` function to do other cool stuff. Below is an example for how to further modify the rate at which UserALE.js collects data, but dropping every other log (odd-even) in the logging queue.
+You can also use the `setLogFilter` function to do other cool stuff. Below is an example for how to further modify the
+rate at which UserALE.js collects data, but dropping every other log (odd-even) in the logging queue.
-```javascript
+```html
<script type="text/javascript">
var logCounter = 0;
window.userale.filter(function (log) {
@@ -88,7 +93,8 @@ This will add your label to all event logs that reference a particular DOM targe
</script>
```
-This cool mapping function adds a progressive count on a given element ("app") and writes to a new log field called "score"
+This cool mapping function adds a progressive count on a given element ("app") and writes to a new log field
+called "score"
```html
</head>
@@ -133,10 +139,13 @@ Test these examples out in our UserALE.js [example page](https://github.com/apac
### Benefits of the UserALE.js API
* No need to dig into our source code
- * Version control is easy and no need to sweat merges--just download the latest [release]({{ '/releases' | prepend: site.baseurl }}), or update via [npm](https://www.npmjs.com/package/useralejs).
+ * Version control is easy and no need to sweat merges--just download the latest [release]({{ '/releases' | prepend: site.baseurl }}),
+ or update via [npm](https://www.npmjs.com/package/flagon-userale).
* Manage logs page-by-page, ideal for large or complex sites
* Use basic or best-practice JS styles and methods to build your own filters, no need to learn weird custom syntax.
## 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.
\ No newline at end of file
+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.
\ No newline at end of file
diff --git a/site/_docs/useralejs/dataschema.md b/site/_docs/useralejs/dataschema.md
index 4d510c8..1491acc 100644
--- a/site/_docs/useralejs/dataschema.md
+++ b/site/_docs/useralejs/dataschema.md
@@ -1,21 +1,292 @@
---
-title: UserALE.js Data Schema
+title: UserALE.js DataSchema
component: useralejs
priority: 4
---
-#The UserALE.js Dataschema
+#The UserALE.js Data Schema
-This guide describes the structure of content of [Apache UserALE.js](https://github.com/apache/incubator-flagon-useralejs) logs, including:
+This guide describes the structure of content of [Apache UserALE.js](https://github.com/apache/incubator-flagon-useralejs)
+logs, including:
* which behaviors UserALE.js listens to;
* which meta data UserALE.js attaches to logs, for context:
* different types of UserALE.js logs, and their usage.
-WIP: Under Construction
+##UserALE.js Logs
+UserALE.js logs, by default, contain a lot more data than you might be used to from other business analytics products.
+The reason for this is simple: business analytics are best suited for click-through analytics (e.g., funnel analysis),
+however, UserALE.js is powerful enough for *workflow analysis*.
-## Contributing
+Workflow analysis is about understanding the complex interdependency between elements and behaviors within and across
+pages. Workflow analysis at this level is really crucial for understanding how people think about the information on
+your site or app, understanding efficiency in information discovery, and for gauging how novices explore pages compared
+to experts/or superusers.
+
+In order to do workflow analysis, and support business analytics, you need a very granular way of looking at user
+interactions with page elements. Below, we'll walk you through some of that data and what it looks like so that you're
+comfortable using it and modifying it.
+
+This is a pretty standard UserALE.js log from our [example test utility](https://github.com/apache/incubator-flagon-useralejs/blob/master/example/index.html):
+
+```html
+ "microTime": 0.185,
+ "minor_ver": "0",
+ "@timestamp": "2019-06-28T16:00:20.790Z",
+ "type": "click",
+ "target": "button#test_button",
+ "details": {
+ "clicks": 13,
+ "shift": false,
+ "meta": false,
+ "alt": false,
+ "ctrl": false
+ },
+ "major_ver": "2",
+ "toolVersion": "2.0.0",
+ "pageReferrer": "",
+ "clientTime": 1561737620520,
+ "userAction": true,
+ "location": {
+ "x": 40,
+ "y": 19
+ },
+ "host": "172.18.0.1",
+ "path": [
+ "button#test_button",
+ "div.container",
+ "body",
+ "html",
+ "#document",
+ "Window"
+ ],
+ "sessionID": "session_1561737570573",
+ "toolName": "Apache UserALE.js Example",
+ "pageTitle": "UserAleJS - Example Page",
+ "logType": "raw",
+ "pageUrl": "file:///Users/jpoore/Documents/Apache_Flagon/test/incubator-flagon-useralejs/example/index.html",
+ "userId": "example-user",
+ "useraleVersion": "2.0.0",
+ "patch_ver": "0"
+ ]
+
+```
+
+It's a lot, but it makes sense in context:
+
+###UserALE.js Event Tracking
+
+The fields below are the 'bread-and-butter' for workflow analysis. They identify what users do and what they interact
+with. Again, UserALE.js is built so that you can get this information from anywhere on your page or app without
+attaching a ton of hooks at src.
+
+```html
+ "type": "click", [this field documents the kind of user behavior observed]
+ "target": "button#test_button", [this field documents the site/app element a user interacted with]
+ "path": [ {this is the DOM path to the "target" element, which is critical for disambiguation between elements}
+ "button#test_button",
+ "div.container",
+ "body",
+ "html",
+ "#document",
+ "Window"]
+
+```
+
+The fields above are also the ones ('target' & 'path') that you may want to specially label for certain elements that
+are important. See our guide on [the UserALE.js API]({{ '/docs/useralejs/API' | prepend: site.baseurl }}) to understand
+how to use this simple utility.
+
+For more information about the kinds of behaviors (event classes) we collect, check out our guide for
+[modifying UserALE.js source code](({{ '/docs/useralejs/modifying' | prepend: site.baseurl }}), which has a useful
+run-down of all our eventHandlers.
+
+###Temporal Handling in UserALE.js
+
+Time is a very important concept in UserALE.js. It's critical to the concept of an event and the sequential aspect of
+workflow analysis. Below are the fields related to temporal data capture:
+
+```html
+ "clientTime": 1561737620520, [UserALE.js collects time from the client when a log is generated]
+ "microTime": 0.185, [When a log is wrtten, we write microtime too, not every database parses it]
+ "@timestamp": "2019-06-28T16:00:20.790Z", [If you use our Elastic backend, you will see indexing time too]
+```
+
+###UserALE.js Meta-Data
+
+You want context? We have all of the things for all of your events:
+
+####Event Context
+
+Every event has a little nuance, UserALE.js gets it all.
+
+What happens if you get like a zillion 'rage-quit' clicks in a really, really short period of time? UserALE.js will add
+to details the number of consecutive clicks, for example that were written into a single log. It will also give you
+context about other inputs at the time of the event (e.g., shift, etc.)
+
+```html
+ "details": {
+ "clicks": 13,
+ "shift": false,
+ "meta": false,
+ "alt": false,
+ "ctrl": false
+ },
+```
+
+But, where was the cursor at the time of a click? In addition to 'target', you'll get location of the cursor two for
+mouseover and click data, too!
+```html
+ "location": {
+ "x": 40,
+ "y": 19
+ },
+```
+[UserALE.js' WebExtension](https://github.com/apache/incubator-flagon-useralejs/tree/master/build) is deployed directly
+into your browser, as a result you'll get browser events. Examples are below, however, with certain browser behavior
+(e.g., new tabs), you'll see our details field has some pretty useful data that isn't available at the page, because it
+hasn't loaded yet, or because it's a browser property!
+
+```html
+ "details": {
+ "audible": false, [audio media on the page?]
+ "title": "Discover - Kibana",
+ "selected": true,
+ "tabId": 64, [uniquely tracks each tab]
+ "windowId": 73, [uniquely tracks each window]
+ "muted": false,
+ "index": 0,
+ "incognito": false, [private browsing?]
+ "url": "http://localhost:5601/app/kibana#/discover?_g=(refreshInterval:(pause:!t)",
+ "active": true, []tab is active?[]
+ "pinned": false
+ },
+```
+
+####Page/App Context
+
+If a user clicks on a thing and you know nothing about that thing, you're toast!
+
+UserALE.js gives a lot context about your page or app. Some are automatically grabbed from the page, some are
+configurable through our [script tag]({{ '/docs/useralejs' | prepend: site.baseurl }})
+
+```html
+ "toolVersion": "2.0.0", [you can give a semantic versioning of your page or tool]
+ "pageReferrer": "", [grabbed from the page, from which page did your users find your page/app]
+ "toolName": "Apache UserALE.js Example", [give your tool an alis through our script tag]
+ "pageTitle": "UserAleJS - Example Page", [page title grabbed from page]
+ "pageUrl": "file:///Users/jpoore/Documents/Apache_Flagon/test/incubator-flagon-useralejs/example/index.html"
+```
+To find out more and how to change the context attached to event logs, check out our
+[modifying UserALE.js source code]({{ '/docs/useralejs/modifying' | prepend: site.baseurl }}) guide.
+
+####User Context
+
+UserALE.js has its own methods for gathering user context, and it can integrate with other methods you might have
+(e.g., cookies)
+
+```html
+ "sessionID": "session_1561737570573", [This session ID is unique to a specific page visit]
+ "userId": "example-user", [You can also pass a unique userId using script-tag methods, or others (e.g., our API)]
+ "host": "172.18.0.1", [IP address is pretty useful to check out the cardinality of seats using your tools]
+```
+
+To see how to pass in a userId from say, a url, check out our [script tag docs]({{ '/docs/useralejs' | prepend: site.baseurl }}).
+
+Other things you might want to do (e.g., cookies) can also be passed to userId via [the UserALE.js API]({{ '/docs/useralejs/API' | prepend: site.baseurl }})
+`mapping` function.
+
+##UserALE.js Log Types
+
+For the most part, UserALE.js logs are uniform. However, there are some variations based on the type of d
+eployment and type of log.
+
+###WebExtension Logs
+
+WebExtension logs from page-level events will look identical to the logs from our script tag method.
+
+WebExtension logs from browser-level events are a bit different, these include focus, activation, and zoom change of the
+browser tab itself. See below:
+
+```html
+"host": "172.18.0.1",
+ "path": null,
+ "microTime": 0.835,
+ "@timestamp": "2019-06-28T18:05:03.681Z",
+ "sessionID": "session_1561741679119",
+ "type": "browser.tabs.onZoomChange",
+ "target": null,
+ "details": {
+ "audible": false,
+ "oldZoomFactor": 1,
+ "selected": true,
+ "tabId": 64,
+ "title": "Discover - Kibana",
+ "windowId": 73,
+ "newZoomFactor": 1,
+ "muted": false,
+ "index": 0,
+ "incognito": false,
+ "url": "http://localhost:5601/app/kibana#/discover?_g=(refreshInterval:(pause:!t),
+ "active": true,
+ "pinned": false
+ },
+ "toolName": null,
+ "toolVersion": null,
+ "clientTime": 1561745100028,
+ "userAction": true,
+ "logType": "raw",
+ "tags": [
+ "_grokparsefailure"
+ ],
+ "location": null,
+ "userId": "nobody",
+ "useraleVersion": null
+ },
+
+```
+
+####Interval Logs
+
+Interval logs are kind of an experimental feature, that write long sequences of the same event to windows. The intent is
+ to be able to capture and abstract high resolution data like 'mouseover' and 'scroll' on similar 'targets' in
+ time-boxed summary windows, rather than a mess of discrete events. You'll note that while interval logs have an index
+ time, they have a start- and end-time instead of a single, discrete time-stamp.
+
+```html
+ "endTime": 1561739434516, [end interval]
+ "minor_ver": "0",
+ "@timestamp": "2019-06-28T16:30:35.734Z",
+ "type": "mouseover",
+ "target": "html", [where were mouseovers observed within the interval]
+ "targetChange": true,
+ "major_ver": "2",
+ "count": 10, [count of disrcete events within the interval]
+ "pageReferrer": "",
+ "toolVersion": "2.0.0",
+ "userAction": false,
+ "duration": 396, [duration of interval in ms]
+ "host": "172.18.0.1",
+ "path": [
+ "html",
+ "#document",
+ "Window"
+ ],
+ "sessionID": "session_1561737570573",
+ "toolName": "Apache UserALE.js Example",
+ "startTime": 1561739434120, [begin interval]
+ "typeChange": true, [were there any other events during the interval?]
+ "pageTitle": "UserAleJS - Example Page",
+ "logType": "interval", [as compared to "raw"]
+ "pageUrl": "file:///Users/jpoore/Documents/Apache_Flagon/test/incubator-flagon-useralejs/example/index.html",
+ "userId": "example-user",
+ "useraleVersion": "2.0.0",
+ "patch_ver": "0"
+```
+## 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.
\ No newline at end of file
+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.
\ No newline at end of file
diff --git a/site/_docs/useralejs/index.md b/site/_docs/useralejs/index.md
index 3ef9959..20c55d8 100644
--- a/site/_docs/useralejs/index.md
+++ b/site/_docs/useralejs/index.md
@@ -10,7 +10,7 @@ priority: 0
*Note:* Work on UserALE.js' documentation is ongoing. Contributions are welcome. To get involved, see our [Contributing]({{ '/docs/contributing' | prepend: site.baseurl }}) 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](https://github.com/apache/incubator-flagon-useralejs/blob/master/README.md). You can use our [build process]({{ '/docs/useralejs/build' | prepend: site.baseurl }}) to create our script, or just use a sample in our [repos](https://github.com/apache/incubator-flagon-useralejs/tree/master/build).
+To start logging with Apache UserALE.js, you can include our script directly in your project. More details can be found in our [README](https://github.com/apache/incubator-flagon-useralejs/blob/master/README.md). You can use our [build process]({{ '/docs/useralejs/build' | prepend: site.baseurl }}) to create our script, use a sample in our [repos](https://github.com/apache/incubator-flagon-useralejs/tree/master/build), or pull our scripts from [npm](https://www.npmjs.com/package/flagon-u [...]
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 (e.g., webserver), and simply include this script tag on the page:
@@ -48,7 +48,7 @@ See our page on [Build and Test]({{ '/docs/useralejs/build' | prepend: site.base
User our [example test utility](https://github.com/apache/incubator-flagon-useralejs/tree/master/example) 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]({{ '/docs/useralejs/build' | prepend: site.baseurl }}) as UserALE.js. You can also use pre-built extension files in our [repo](https://github.com/apache/incubator-flagon-useralejs/tree/FLAGON- [...]
+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]({{ '/docs/useralejs/build' | prepend: site.baseurl }}) as UserALE.js. You can also use pre-built extension files in our [repo](https://github.com/apache/incubator-flagon-useralejs/tree/master/ [...]
When you're ready to deploy the UserALE.js web extension, follow the instructions below:
diff --git a/site/_docs/useralejs/modifying.md b/site/_docs/useralejs/modifying.md
index e0ee466..92d2441 100644
--- a/site/_docs/useralejs/modifying.md
+++ b/site/_docs/useralejs/modifying.md
@@ -1,12 +1,15 @@
---
-title: Modifying UserALE.js
+title: Modifying
component: useralejs
priority: 3
---
# Customizing UserALE.js Logs through Source Code Modifications
-[Apache UserALE.js](https://github.com/apache/incubator-flagon-useralejs) makes it easy for you to capture *every* user behavior on your webpage or application. But, you might not need all that data and you might not care to worry about scaling your logging data store. Fortunately, UserALE.js also makes it easy for your to manage, and curate your logging scheme.
+[Apache UserALE.js](https://github.com/apache/incubator-flagon-useralejs) makes it easy for you to capture *every* user
+behavior on your webpage or application. But, you might not need all that data and you might not care to worry about
+scaling your logging data store. Fortunately, UserALE.js also makes it easy for your to manage, and curate your
+logging scheme.
This guide walks you through how to modify UserALE.js log data and behavior through source code modification.
@@ -20,7 +23,7 @@ UserALE.js src is intuitively abstracted into few different files"
* [configure](https://github.com/apache/incubator-flagon-useralejs/blob/master/src/configure.js): set special custom parameters, like passing a unqiue userID into UserALE.js logs.
* [getInitialSettings](https://github.com/apache/incubator-flagon-useralejs/blob/master/src/getInitialSettings.js): modify HTML5 parameters passed through the script tag.
* [main](https://github.com/apache/incubator-flagon-useralejs/blob/master/src/main.js): attaches event handlers and adds logs to queue (probably want to leave alone).
- * [packageLogs](https://github.com/apache/incubator-flagon-useralejs/blob/master/src/packageLogs.js): modify to configure how user behaviors are added to data schema, and which meta data is added from the page.
+ * [packageLogs](https://github.com/apache/incubator-flagon-useralejs/blob/master/src/packageLogs.js): modify to configure how user behaviors are added to data schema, and meta data added from the page.
* [sendLogs](https://github.com/apache/incubator-flagon-useralejs/blob/master/src/sendLogs.js): modify how logs are sent to logging server, etc. (be careful here, too).
###Usage
@@ -35,6 +38,7 @@ Once you modify source, you'll need to rebuild UserALE.js scripts and webextensi
You can modify some of the events UserALE.js by editing vars in `attacheHandlers`.
+
```javascript
you can modify the events UserALE.js by editing vars in `attacheHandlers`
var events;
@@ -47,6 +51,7 @@ var windowEvents = ['load', 'blur', 'focus'];
```
You can modify which events UserALE.js captures in it's 'raw' log stream, by modifying the var `events`:
+
```javascript
/* Comment out event types in the `events` var for granular modification of UserALE.js behavior */
@@ -67,12 +72,15 @@ export function defineDetails(config) {
'dragend' : null,
'drag' : null,
'drop' : null,
- 'keydown' : config.logDetails ? function(e) { return { 'key' : e.keyCode, 'ctrl' : e.ctrlKey, 'alt' : e.altKey, 'shift' : e.shiftKey, 'meta' : e.metaKey }; } : null,
+ 'keydown' : config.logDetails ? function(e) { return { 'key' : e.keyCode, 'ctrl' : e.ctrlKey, 'alt' : e.altKey,
+ 'shift' : e.shiftKey, 'meta' : e.metaKey }; } : null,
/*'mouseover' : null,*/ #Aliasing out events from the "events" list removes that class from your event stream.
'submit' : null
```
You can eliminate the `interval` log stream altogether by modifying the `attachHandlers` configs:
+
+
```javascript
export function attachHandlers(config) {
defineDetails(config);
@@ -95,6 +103,7 @@ export function attachHandlers(config) {
The easiest way to make these changes is by modifying the var `log`:
+
```javascript
/* Comment or add fields to be included in your logs, pulling in other data from configs, window, or documents */
var log = {
@@ -120,10 +129,14 @@ The easiest way to make these changes is by modifying the var `log`:
### Benefits Modifying UserALE.js Logs via src:
* Full control of your log streams
- * With simple modification to src you can package and build multiple UserALE.js scripts for page-to-page modification of log streams.
+ * With simple modification to src you can package and build multiple UserALE.js scripts for page-to-page modification
+ of log streams.
* Modify the behavior of our webExtension
- * Ideal in cases where you don't want to integrate UserALE.js into your CD pipeline, just pass around pre-built scripts that suite your needs.
+ * Ideal in cases where you don't want to integrate UserALE.js into your CD pipeline, just pass around pre-built scripts
+ that suite your needs.
## 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.
\ No newline at end of file
+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.
\ No newline at end of file