Skip to content
Permalink
Browse files
updates to site docs
  • Loading branch information
poorejc committed Jun 19, 2022
1 parent 8770fce commit 8e9cbb313edadcd9ede579009c6c4063bc4e2cc3
Showing 7 changed files with 95 additions and 40 deletions.
@@ -15,16 +15,21 @@ latitude in customizing and curating your logs.

To invoke the API, simply add additional javascript code blocks under your UserALE.js script tag.

Don't forget to add the UserALE.js script tag! For an in depth example, see our [Getting Started Guide]({{ '/docs/useralejs' | prepend: site.baseurl }})) and our [example test utility](https://github.com/apache/incubator-flagon-useralejs/tree/master/example).
Don't forget to add UserALE.js to your project!

It can be deployed as either script-tag, NPM module, or via CDN! For in-depth example, see our [Getting Started Guide]({{ '/docs/useralejs' | prepend: site.baseurl }})) or source [README.md](https://github.com/apache/incubator-flagon-useralejs#usage).

Also, check out our[example test utility](https://github.com/apache/incubator-flagon-useralejs/tree/master/example) so that you can experiment with logs in your terminal!

The following API examples use script-tag deployment methods for illustration:

```html
<head>
<title>UserAleJS - Example Page</title>
<!--
Add the UserALE.js script tag to the top of your doc
-->
<script src="/path/to/userale-2.1.1.min.js" data-url="http://yourLoggingUrl"></script>
<script src="/path/to/userale-2.3.0.min.js" data-url="http://yourLoggingUrl"></script>
```

## `options` Examples
@@ -39,7 +44,7 @@ Try out the options API to pass dynamic page data into your UserALE.js params pa
const changeMe = "me";
window.userale.options({
"userId": changeMe,
"version": "2.1.1",
"version": "2.3.0",
"sessionID": "4"
})
</script>
@@ -163,9 +168,10 @@ called "score"

```


Test these examples out in our UserALE.js [example page](https://github.com/apache/incubator-flagon-useralejs/blob/master/example/index.html) test utility!

See more [UserALE.js API Examples]()

### 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 }}),
@@ -175,6 +181,6 @@ Test these examples out in our UserALE.js [example page](https://github.com/apac

## Contributing

Contributions are welcome! Simply [submit an issue report](https://issues.apache.org/jira/browse/FLAGON) for problems
Contributions are welcome! Simply [submit an issue](https://github.com/apache/incubator-flagon-useralejs/issues) 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.
incorporate it into UserALE.js. We also love Pull Requests!
@@ -114,3 +114,9 @@ npm run test
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).

Further instructions can be found in our [README](https://github.com/apache/incubator-flagon-useralejs/blob/master/README.md)

## Contributing

Contributions are welcome! Simply [submit an issue](https://github.com/apache/incubator-flagon-useralejs/issues) 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!
@@ -289,6 +289,6 @@ Interval logs have a start- and end-time instead of a single, discrete time-stam
```
## Contributing

Contributions are welcome! Simply [submit an issue report](https://issues.apache.org/jira/browse/FLAGON) for problems
Contributions are welcome! Simply [submit an issue](https://github.com/apache/incubator-flagon-useralejs/issues) 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.
incorporate it into UserALE.js. We also love Pull Requests!
@@ -8,30 +8,60 @@ priority: 0
[Apache UserALE.js](https://github.com/apache/incubator-flagon-useralejs) 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]({{ '/docs/contributing' | prepend: site.baseurl }}) guide.
### Include UserALE.js in your project
## 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, 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-userale).

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:
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:

```html
<script src="/path/to/userale-2.2.0.min.js"></script>
npm install flagon-userale
```

Alternatively if you want to use a CDN, you can add the script as follows
### Include UserALE.js as a `module`:

```html
<script src="https://cdn.jsdelivr.net/npm/flagon-userale@2.1.1/build/userale-2.2.0.min.js"></script>
import * as userale from 'flagon-userale';

or

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

Our [webpack example](https://github.com/apache/incubator-flagon-useralejs/tree/master/example/webpackUserAleExample) illustrates this use-case.

### Include UserALE.js as a `script-tag`:

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

Our [script tag example](https://github.com/apache/incubator-flagon-useralejs/tree/master/example) illustrates this use-case

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

```html
npm install --save-dev flagon-userale
```

### Include UserALE.js via a CDN:

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

This tag will execute the UserALE.js script in your, with no other modifications to your project needed!
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.

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

**Configure UserALE.js through the Script Tag**
## Configure UserALE.js

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, one thing you'll need to do is set the URL (location) of your minified UserALE.js script:
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:

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

The complete list of configurable options is:
@@ -47,12 +77,15 @@ The complete list of configurable options is:
| data-log-details | Toggle detailed logs (keys pressed and input/change values) | false |
| 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-tool | Name of tool being logged | null |

**NOTE** These options are also available through our [API]({{ '/docs/useralejs/API' | prepend: site.baseurl }}), which support deploying UserALE.js as an NPM `module.`

See our page on [Build and Test]({{ '/docs/useralejs/build' | prepend: site.baseurl }}) 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](https://github.com/apache/incubator-flagon-useralejs/tree/master/build).

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
Use 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/master/build).

@@ -76,8 +109,12 @@ When you're ready to deploy the UserALE.js web extension, follow the instruction
1. Press Ok, and confirm that 'UserALE Extension' appears in the list
1. 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](https://github.com/apache/incubator-flagon-useralejs/blob/FLAGON-336/src/UserALEWebExtension/README.md).

## Options

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.
## Contributing

Contributions are welcome! Simply [submit an issue](https://github.com/apache/incubator-flagon-useralejs/issues) 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!
@@ -16,7 +16,7 @@ This guide walks you through how to modify UserALE.js log data and behavior thro

We're starting with this method because it will give context to others methods, like our script tag and API (below).

UserALE.js src is intuitively abstracted into few different files"
UserALE.js src is intuitively abstracted into few different files:

* [attachHandlers](https://github.com/apache/incubator-flagon-useralejs/blob/master/src/attachHandlers.js): configure which user behaviors UserALE.js listens for and event handlers here.
* [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.
@@ -138,6 +138,6 @@ The easiest way to make these changes is by modifying the var `log`:
## Contributing
Contributions are welcome! Simply [submit an issue report](https://issues.apache.org/jira/browse/FLAGON) for problems
Contributions are welcome! Simply [submit an issue](https://github.com/apache/incubator-flagon-useralejs/issues) 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.
incorporate it into UserALE.js. We also love Pull Requests!
@@ -7,6 +7,12 @@ priority: 5

### Enable Cross-Origin Resource Sharing (CORS)

The logs generated by [Apache UserALE.js](https://github.com/apache/incubator-flagon-useralejs) are sent to a logging server 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.
The logs generated by [Apache UserALE.js](https://github.com/apache/incubator-flagon-useralejs) are sent to a logging server which is configured in the script tag or via .js scripts using our API. 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 [enable-cors.org](http://enable-cors.org/index.html).

## Contributing

Contributions are welcome! Simply [submit an issue](https://github.com/apache/incubator-flagon-useralejs/issues) 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!
@@ -18,7 +18,7 @@
Apache Flagon artifacts are always distributed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, version 2.0</a>.
</p>

<h1>Apache Flagon UserALE.js (Incubating) version 2.2.0</h1>
<h1>Apache Flagon UserALE.js (Incubating) version 2.3.0</h1>

<p>
Apache Flagon UserALE.js is a client side instrumentation library written in JavaScript designed for easy deployment and lightweight configuration in gathering logs from your web applications for user behavioral analytics.
@@ -45,24 +45,24 @@ <h2>Downloads</h2>
</thead>
<tbody>
<tr>
<td><a style="padding:0 15px 0 15px;" href="http://www.apache.org/dyn/closer.lua/incubator/flagon/apache-flagon-useralejs-incubating-2.2.0/apache-flagon-useralejs-incubating-2.2.0-bin.tar.gz">Apache UserALE.js 2.2.0 Binaries (tar.gz)</a> </td>
<td><a style="padding:0 45px 0 45px;" href="https://downloads.apache.org/incubator/flagon/apache-flagon-useralejs-incubating-2.2.0/apache-flagon-useralejs-incubating-2.2.0-bin.tar.gz.asc">asc (tar.gz)</a> </td>
<td><a style="padding:0 30px 0 30px;" href="https://downloads.apache.org/incubator/flagon/apache-flagon-useralejs-incubating-2.2.0/apache-flagon-useralejs-incubating-2.2.0-bin.tar.gz.sha512">sha512 (tar.gz)</a> </td>
<td><a style="padding:0 15px 0 15px;" href="http://www.apache.org/dyn/closer.lua/incubator/flagon/apache-flagon-useralejs-incubating-2.3.0/apache-flagon-useralejs-incubating-2.3.0-bin.tar.gz">Apache UserALE.js 2.3.0 Binaries (tar.gz)</a> </td>
<td><a style="padding:0 45px 0 45px;" href="https://downloads.apache.org/incubator/flagon/apache-flagon-useralejs-incubating-2.3.0/apache-flagon-useralejs-incubating-2.3.0-bin.tar.gz.asc">asc (tar.gz)</a> </td>
<td><a style="padding:0 30px 0 30px;" href="https://downloads.apache.org/incubator/flagon/apache-flagon-useralejs-incubating-2.3.0/apache-flagon-useralejs-incubating-2.3.0-bin.tar.gz.sha512">sha512 (tar.gz)</a> </td>
</tr>
<tr>
<td><a style="padding:0 15px 0 15px;" href="http://www.apache.org/dyn/closer.lua/incubator/flagon/apache-flagon-useralejs-incubating-2.2.0/apache-flagon-useralejs-incubating-2.2.0-bin.zip">Apache UserALE.js 2.2.0 Binaries (zip)</a></td>
<td><a style="padding:0 45px 0 45px;" href="https://downloads.apache.org/incubator/flagon/apache-flagon-useralejs-incubating-2.2.0/apache-flagon-useralejs-incubating-2.2.0-bin.zip.asc">asc (zip)</a></td>
<td><a style="padding:0 30px 0 30px;" href="https://downloads.apache.org/incubator/flagon/apache-flagon-useralejs-incubating-2.2.0/apache-flagon-useralejs-incubating-2.2.0-bin.zip.sha512">sha512 (zip)</a></td>
<td><a style="padding:0 15px 0 15px;" href="http://www.apache.org/dyn/closer.lua/incubator/flagon/apache-flagon-useralejs-incubating-2.3.0/apache-flagon-useralejs-incubating-2.3.0-bin.zip">Apache UserALE.js 2.3.0 Binaries (zip)</a></td>
<td><a style="padding:0 45px 0 45px;" href="https://downloads.apache.org/incubator/flagon/apache-flagon-useralejs-incubating-2.3.0/apache-flagon-useralejs-incubating-2.3.0-bin.zip.asc">asc (zip)</a></td>
<td><a style="padding:0 30px 0 30px;" href="https://downloads.apache.org/incubator/flagon/apache-flagon-useralejs-incubating-2.3.0/apache-flagon-useralejs-incubating-2.3.0-bin.zip.sha512">sha512 (zip)</a></td>
</tr>
<tr>
<td><a style="padding:0 15px 0 15px;" href="http://www.apache.org/dyn/closer.lua/incubator/flagon/apache-flagon-useralejs-incubating-2.2.0/apache-flagon-useralejs-incubating-2.2.0-src.tar.gz">Apache UserALE.js 2.2.0 Source (tar.gz)</a></td>
<td><a style="padding:0 45px 0 45px;" href="https://downloads.apache.org/incubator/flagon/apache-flagon-useralejs-incubating-2.2.0/apache-flagon-useralejs-incubating-2.2.0-src.tar.gz.asc">asc (tar.gz)</a> </td>
<td><a style="padding:0 30px 0 30px;" href="https://downloads.apache.org/incubator/flagon/apache-flagon-useralejs-incubating-2.2.0/apache-flagon-useralejs-incubating-2.2.0-src.tar.gz.sha512">sha512 (tar.gz)</a> </td>
<td><a style="padding:0 15px 0 15px;" href="http://www.apache.org/dyn/closer.lua/incubator/flagon/apache-flagon-useralejs-incubating-2.3.0/apache-flagon-useralejs-incubating-2.3.0-src.tar.gz">Apache UserALE.js 2.3.0 Source (tar.gz)</a></td>
<td><a style="padding:0 45px 0 45px;" href="https://downloads.apache.org/incubator/flagon/apache-flagon-useralejs-incubating-2.3.0/apache-flagon-useralejs-incubating-2.3.0-src.tar.gz.asc">asc (tar.gz)</a> </td>
<td><a style="padding:0 30px 0 30px;" href="https://downloads.apache.org/incubator/flagon/apache-flagon-useralejs-incubating-2.3.0/apache-flagon-useralejs-incubating-2.3.0-src.tar.gz.sha512">sha512 (tar.gz)</a> </td>
</tr>
<tr>
<td><a style="padding:0 15px 0 15px;" href="http://www.apache.org/dyn/closer.lua/incubator/flagon/apache-flagon-useralejs-incubating-2.2.0/apache-flagon-useralejs-incubating-2.2.0-src.zip">Apache UserALE.js 2.2.0 Source (zip)</a></td>
<td><a style="padding:0 45px 0 45px;" href="https://downloads.apache.org/incubator/flagon/apache-flagon-useralejs-incubating-2.2.0/apache-flagon-useralejs-incubating-2.2.0-src.zip.asc">asc (zip)</a></td>
<td><a style="padding:0 30px 0 30px;" href="https://downloads.apache.org/incubator/flagon/apache-flagon-useralejs-incubating-2.2.0/apache-flagon-useralejs-incubating-2.2.0-src.zip.sha512">sha512 (zip)</a></td>
<td><a style="padding:0 15px 0 15px;" href="http://www.apache.org/dyn/closer.lua/incubator/flagon/apache-flagon-useralejs-incubating-2.3.0/apache-flagon-useralejs-incubating-2.3.0-src.zip">Apache UserALE.js 2.3.0 Source (zip)</a></td>
<td><a style="padding:0 45px 0 45px;" href="https://downloads.apache.org/incubator/flagon/apache-flagon-useralejs-incubating-2.3.0/apache-flagon-useralejs-incubating-2.3.0-src.zip.asc">asc (zip)</a></td>
<td><a style="padding:0 30px 0 30px;" href="https://downloads.apache.org/incubator/flagon/apache-flagon-useralejs-incubating-2.3.0/apache-flagon-useralejs-incubating-2.3.0-src.zip.sha512">sha512 (zip)</a></td>
</tr>
</tbody>
</table>

0 comments on commit 8e9cbb3

Please sign in to comment.