blob: 273c3b53993818916a7e1227c03cf5ca666e4db1 [file]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>The UserALE.js API</title>
<meta name="description" content="Apache UserALE.js features a robust API that allows you customize official Apache Flagon UserALE.js builds page-by-page to suite your needs.">
<link rel="stylesheet" type="text/css" href="/semantic/dist/semantic.min.css">
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.1/jquery.min.js"></script>
<script src="/semantic/dist/semantic.min.js"></script>
<script src="https://d3js.org/d3.v4.min.js"></script>
<script src="/js/main.js"></script>
<link rel="stylesheet" href="/assets/main.css">
<link rel="canonical" href="http://flagon.incubator.apache.org/docs/useralejs/API/">
<link rel="alternate" type="application/rss+xml" title="Apache Flagon" href="/feed.xml">
</head>
<body>
<div class="site-header">
<div id="main-menu" class="ui inverted padded fixed top borderless menu">
<a class="site-title" href="/">
<h3 class="ui inverted header item">Apache Flagon</h3>
</a>
<div class="right menu">
<div class="ui dropdown item">
Products
<div class="menu">
<a class="item" href="/stack">Stack</a>
<a class="item" href="/userale">UserALE</a>
<a class="item" href="/distill">Distill</a>
<a class="item" href="/tap">Tap</a>
<a class="item" href="/stout">Stout</a>
</div>
</div>
<div class="ui dropdown item">
<a href="/docs">Docs</a>
<div class="menu">
<a class="item" href="/docs/stack">Stack</a>
<a class="item" href="/docs/userale">UserALE</a>
<a class="item" href="/docs/useralejs">UserALE.js</a>
<a class="item" href="/docs/useralepy">UserALE.py</a>
<a class="item" href="/docs/distill">Distill</a>
<a class="item" href="/docs/tap">Tap</a>
<a class="item" href="/docs/stout">Stout</a>
</div>
</div>
<a class="item" href="/releases">Releases</a>
<a class="item" href="/community">Community</a>
</div>
</div>
</div>
<div class="main-wrapper">
<div class="docs-wrapper">
<div class="docs-sidebar">
<!-- <div class="ui inverted list">
<a class="item" href="/docs">About the Docs</a>
</div> -->
<div id="docs-nav" class="ui inverted accordion">
<div class="title">
<i class="dropdown icon"></i>
Apache Flagon
</div>
<div class="content">
<div class="ui inverted bulleted list docs-list">
<a class="item" href="/docs/">About the Docs</a>
<a class="item" href="/docs/contributing/">Contributing</a>
</div>
</div>
<div class="title">
<i class="dropdown icon"></i>
Stack
</div>
<div class="content">
<div class="ui inverted bulleted list docs-list">
<a class="item" href="/docs/stack/">Getting Started</a>
<a class="item" href="/docs/stack/scaling/">Scaling Considerations</a>
</div>
</div>
<div class="title">
<i class="dropdown icon"></i>
UserALE
</div>
<div class="content">
<div class="ui inverted bulleted list docs-list">
<a class="item" href="/docs/userale/">About UserALE</a>
</div>
</div>
<div class="active title">
<i class="dropdown icon"></i>
UserALE.js
</div>
<div class="active content">
<div class="ui inverted bulleted list docs-list">
<a class="item" href="/docs/useralejs/">Getting Started</a>
<a class="item" href="/docs/useralejs/build/">UserALE.js Build and Test</a>
<a class="item" href="/docs/useralejs/API/">The UserALE.js API</a>
<a class="item" href="/docs/useralejs/modifying/">Modifying UserALE.js Source Code</a>
<a class="item" href="/docs/useralejs/dataschema/">UserALE.js' Data Schema</a>
<a class="item" href="/docs/useralejs/troubleshooting/">Troubleshooting</a>
</div>
</div>
<div class="title">
<i class="dropdown icon"></i>
UserALE.py
</div>
<div class="content">
<div class="ui inverted bulleted list docs-list">
<a class="item" href="/docs/useralepy/">Installation</a>
<a class="item" href="/docs/useralepy/start.html">Getting Started</a>
<a class="item" href="/docs/useralepy/api.html">API Documentation</a>
<a class="item" href="/docs/useralepy/changelog.html">Changelog</a>
</div>
</div>
<div class="title">
<i class="dropdown icon"></i>
Distill
</div>
<div class="content">
<div class="ui inverted bulleted list docs-list">
<a class="item" href="/docs/distill/">Installation</a>
<a class="item" href="/docs/distill/start.html">Getting Started</a>
<a class="item" href="/docs/distill/api.html">API Documentation</a>
<a class="item" href="/docs/distill/analytics.html">Apache Distill Analytics</a>
<a class="item" href="/docs/distill/http.html">Apache Distill HTTP Client</a>
<a class="item" href="/docs/distill/models.html">Apache Distill Models</a>
<a class="item" href="/docs/distill/utilities.html">Apache Distill Utilities</a>
<a class="item" href="/docs/distill/changelog.html">Changelog</a>
</div>
</div>
<div class="title">
<i class="dropdown icon"></i>
Tap
</div>
<div class="content">
<div class="ui inverted bulleted list docs-list">
<a class="item" href="/docs/tap/">Getting Started</a>
</div>
</div>
<div class="title">
<i class="dropdown icon"></i>
Stout
</div>
<div class="content">
<div class="ui inverted bulleted list docs-list">
<a class="item" href="/docs/stout/">About Stout</a>
<a class="item" href="/docs/stout/start.html">Getting Started</a>
</div>
</div>
</div>
</div>
<div class="docs-content">
<h2 class="ui header">The UserALE.js API</h2>
<p><a href="https://github.com/apache/incubator-flagon-useralejs">Apache UserALE.js</a> features a robust API that allows you
customize official Apache Flagon UserALE.js <a href="https://github.com/apache/incubator-flagon-useralejs/tree/master/build">builds</a> page-by-page to suite your needs.</p>
<p>The API exposes a number of functions, including: <code class="highlighter-rouge">options</code>, <code class="highlighter-rouge">setLogFilter</code>, &amp; <code class="highlighter-rouge">setLogMapper</code>. With these two powerful functions, you have a lot of
latitude in customizing and curating your logs.</p>
<h1 id="api-usage">API Usage</h1>
<p>To invoke the API, simply add additional javascript code blocks under your UserALE.js script tag.</p>
<p>Don’t forget to add UserALE.js to your project!</p>
<p>It can be deployed as either script-tag, NPM module, or via CDN! For in-depth example, see our <a href="/docs/useralejs">Getting Started Guide</a>) or source <a href="https://github.com/apache/incubator-flagon-useralejs#usage">README.md</a>.</p>
<p>Also, check out our<a href="https://github.com/apache/incubator-flagon-useralejs/tree/master/example">example test utility</a> so that you can experiment with logs in your terminal!</p>
<p>The following API examples use script-tag deployment methods for illustration:</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;head&gt;</span>
<span class="nt">&lt;title&gt;</span>UserAleJS - Example Page<span class="nt">&lt;/title&gt;</span>
<span class="c">&lt;!--
Add the UserALE.js script tag to the top of your doc
--&gt;</span>
<span class="nt">&lt;script </span><span class="na">src=</span><span class="s">"/path/to/userale-2.3.0.min.js"</span> <span class="na">data-url=</span><span class="s">"http://yourLoggingUrl"</span><span class="nt">&gt;&lt;/script&gt;</span>
</code></pre></div></div>
<h2 id="options-examples"><code class="highlighter-rouge">options</code> Examples</h2>
<p><code class="highlighter-rouge">options</code> allows you to modify UserALE.js script tag parameters. This can be particularly useful if need to pass additional data about users from your page into the logging parameters, like username and sessionID. You can build variables constructors that pass data from form data or browser storage to UserALE’s paramters.</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c">&lt;!--
Try out the options API to pass dynamic page data into your UserALE.js params page by page.
--&gt;</span>
<span class="nt">&lt;script </span><span class="na">type=</span><span class="s">"text/javascript"</span><span class="nt">&gt;</span>
<span class="kd">const</span> <span class="nx">changeMe</span> <span class="o">=</span> <span class="s2">"me"</span><span class="p">;</span>
<span class="nb">window</span><span class="p">.</span><span class="nx">userale</span><span class="p">.</span><span class="nx">options</span><span class="p">({</span>
<span class="s2">"userId"</span><span class="p">:</span> <span class="nx">changeMe</span><span class="p">,</span>
<span class="s2">"version"</span><span class="p">:</span> <span class="s2">"2.3.0"</span><span class="p">,</span>
<span class="s2">"sessionID"</span><span class="p">:</span> <span class="s2">"4"</span>
<span class="p">})</span>
<span class="nt">&lt;/script&gt;</span>
</code></pre></div></div>
<h2 id="setlogfilter-examples"><code class="highlighter-rouge">setLogFilter</code> Examples</h2>
<p><code class="highlighter-rouge">setLogFilter</code> allows you to eliminate log data you don’t need or want from your log stream:</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c">&lt;!--
Add additional code blocks to set the filters you want
This simple array filter pulls mouseover data out of your log stream
--&gt;</span>
<span class="nt">&lt;script </span><span class="na">type=</span><span class="s">"text/javascript"</span><span class="nt">&gt;</span>
<span class="nb">window</span><span class="p">.</span><span class="nx">userale</span><span class="p">.</span><span class="nx">filter</span><span class="p">(</span><span class="kd">function</span> <span class="p">(</span><span class="nx">log</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="p">(</span><span class="nx">log</span><span class="p">.</span><span class="nx">type</span> <span class="o">!=</span> <span class="s1">'mouseover'</span><span class="p">);</span>
<span class="p">});</span>
<span class="nt">&lt;/script&gt;</span>
</code></pre></div></div>
<p>Here is one UserALE.js filter to rule them all!</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c">&lt;!--
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.
--&gt;</span>
<span class="nt">&lt;script </span><span class="na">type=</span><span class="s">"text/javascript"</span><span class="nt">&gt;</span>
<span class="kd">var</span> <span class="nx">type_array</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'mouseup'</span><span class="p">,</span> <span class="s1">'mouseover'</span><span class="p">,</span> <span class="s1">'dblclick'</span><span class="p">,</span> <span class="s1">'blur'</span><span class="p">,</span> <span class="s1">'focus'</span><span class="p">]</span>
<span class="kd">var</span> <span class="nx">logType_array</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'interval'</span><span class="p">]</span>
<span class="nb">window</span><span class="p">.</span><span class="nx">userale</span><span class="p">.</span><span class="nx">filter</span><span class="p">(</span><span class="kd">function</span> <span class="p">(</span><span class="nx">log</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="o">!</span><span class="nx">type_array</span><span class="p">.</span><span class="nx">includes</span><span class="p">(</span><span class="nx">log</span><span class="p">.</span><span class="nx">type</span><span class="p">)</span> <span class="o">&amp;&amp;</span> <span class="o">!</span><span class="nx">logType_array</span><span class="p">.</span><span class="nx">includes</span><span class="p">(</span><span class="nx">log</span><span class="p">.</span><span class="nx">logType</span><span class="p">);</span>
<span class="p">});</span>
<span class="nt">&lt;/script&gt;</span>
</code></pre></div></div>
<p>You can also use the <code class="highlighter-rouge">setLogFilter</code> 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.</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <span class="nt">&lt;script </span><span class="na">type=</span><span class="s">"text/javascript"</span><span class="nt">&gt;</span>
<span class="kd">var</span> <span class="nx">logCounter</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="nb">window</span><span class="p">.</span><span class="nx">userale</span><span class="p">.</span><span class="nx">filter</span><span class="p">(</span><span class="kd">function</span> <span class="p">(</span><span class="nx">log</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="p">(</span><span class="nx">logCounter</span><span class="o">++</span> <span class="o">%</span> <span class="mi">2</span><span class="p">);</span>
<span class="p">});</span>
<span class="nt">&lt;/script&gt;</span>
</code></pre></div></div>
<h2 id="setlogmapper-examples"><code class="highlighter-rouge">setLogMapper</code> Examples</h2>
<p><code class="highlighter-rouge">setLogMapper</code> allows you to modify or add new fields to UserALE.js logs.</p>
<p>This simple mapping function adds a new log field for custom labels you want to attach to certain elements:</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c">&lt;!--
This will add your label to all event logs that reference a particular DOM target.
--&gt;</span>
<span class="nt">&lt;script </span><span class="na">type=</span><span class="s">"text/javascript"</span><span class="nt">&gt;</span>
<span class="nb">window</span><span class="p">.</span><span class="nx">userale</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="kd">function</span> <span class="p">(</span><span class="nx">log</span><span class="p">)</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">targetsForLabels</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"button#test_button"</span><span class="p">];</span>
<span class="k">if</span> <span class="p">(</span><span class="nx">targetsForLabels</span><span class="p">.</span><span class="nx">includes</span><span class="p">(</span><span class="nx">log</span><span class="p">.</span><span class="nx">target</span><span class="p">))</span> <span class="p">{</span>
<span class="k">return</span> <span class="nb">Object</span><span class="p">.</span><span class="nx">assign</span><span class="p">({},</span> <span class="nx">log</span><span class="p">,</span> <span class="p">{</span> <span class="na">CustomLabel</span><span class="p">:</span> <span class="s2">"Click me!"</span> <span class="p">});</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
<span class="k">return</span> <span class="nx">log</span><span class="p">;</span>
<span class="p">}</span>
<span class="p">});</span>
<span class="nt">&lt;/script&gt;</span>
</code></pre></div></div>
<p>This cool mapping function adds a progressive count on a given element (“app”) and writes to a new log field
called “score”</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <span class="nt">&lt;/head&gt;</span>
<span class="nt">&lt;body&gt;</span>
<span class="nt">&lt;div</span> <span class="na">id=</span><span class="s">"app"</span><span class="nt">&gt;</span>
<span class="nt">&lt;button</span> <span class="na">id=</span><span class="s">"increment"</span><span class="nt">&gt;</span>+<span class="nt">&lt;/button&gt;</span>
<span class="nt">&lt;button</span> <span class="na">id=</span><span class="s">"decrement"</span><span class="nt">&gt;</span>-<span class="nt">&lt;/button&gt;</span>
<span class="nt">&lt;div</span> <span class="na">id=</span><span class="s">"scoreboard"</span><span class="nt">&gt;&lt;/div&gt;</span>
<span class="nt">&lt;/div&gt;</span>
<span class="nt">&lt;/script&gt;</span>
<span class="nt">&lt;script </span><span class="na">type=</span><span class="s">"text/javascript"</span><span class="nt">&gt;</span>
<span class="kd">var</span> <span class="nx">score</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="kd">var</span> <span class="nx">scoreBoard</span> <span class="o">=</span> <span class="nb">document</span><span class="p">.</span><span class="nx">getElementById</span><span class="p">(</span><span class="s1">'scoreboard'</span><span class="p">);</span>
<span class="nx">scoreBoard</span><span class="p">.</span><span class="nx">innerText</span> <span class="o">=</span> <span class="s1">'0'</span><span class="p">;</span>
<span class="kd">function</span> <span class="nx">setScore</span><span class="p">(</span><span class="nx">nextScore</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">score</span> <span class="o">=</span> <span class="nx">nextScore</span><span class="p">;</span>
<span class="nx">scoreBoard</span><span class="p">.</span><span class="nx">innerText</span> <span class="o">=</span> <span class="nb">String</span><span class="p">(</span><span class="nx">score</span><span class="p">);</span>
<span class="p">}</span>
<span class="nb">document</span><span class="p">.</span><span class="nx">getElementById</span><span class="p">(</span><span class="s1">'increment'</span><span class="p">).</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s1">'click'</span><span class="p">,</span> <span class="kd">function</span> <span class="p">()</span> <span class="p">{</span>
<span class="nx">setScore</span><span class="p">(</span><span class="nx">score</span> <span class="o">+</span> <span class="mi">1</span><span class="p">);</span>
<span class="p">});</span>
<span class="nb">document</span><span class="p">.</span><span class="nx">getElementById</span><span class="p">(</span><span class="s1">'decrement'</span><span class="p">).</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s1">'click'</span><span class="p">,</span> <span class="kd">function</span> <span class="p">()</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="nx">score</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">setScore</span><span class="p">(</span><span class="nx">score</span> <span class="o">-</span> <span class="mi">1</span><span class="p">);</span>
<span class="p">}</span>
<span class="p">});</span>
<span class="nb">window</span><span class="p">.</span><span class="nx">userale</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="kd">function</span> <span class="p">(</span><span class="nx">log</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="nb">Object</span><span class="p">.</span><span class="nx">assign</span><span class="p">({},</span> <span class="nx">log</span><span class="p">,</span> <span class="p">{</span> <span class="na">score</span><span class="p">:</span> <span class="nx">score</span> <span class="p">});</span> <span class="c1">// Add the "score" property to the log</span>
<span class="p">});</span>
<span class="nt">&lt;/script&gt;</span>
<span class="nt">&lt;/body&gt;</span>
<span class="nt">&lt;/html&gt;</span>
</code></pre></div></div>
<p>Test these examples out in our UserALE.js <a href="https://github.com/apache/incubator-flagon-useralejs/blob/master/example/index.html">example page</a> test utility!</p>
<p>See more <a href="">UserALE.js API Examples</a></p>
<h3 id="benefits-of-the-useralejs-api">Benefits of the UserALE.js API</h3>
<ul>
<li>No need to dig into our source code</li>
<li>Version control is easy and no need to sweat merges–just download the latest <a href="/releases">release</a>,
or update via <a href="https://www.npmjs.com/package/flagon-userale">npm</a>.</li>
<li>Manage logs page-by-page, ideal for large or complex sites</li>
<li>Use basic or best-practice JS styles and methods to build your own filters, no need to learn weird custom syntax.</li>
</ul>
<h2 id="contributing">Contributing</h2>
<p>Contributions are welcome! Simply <a href="https://github.com/apache/incubator-flagon-useralejs/issues">submit an issue</a> 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!</p>
</div>
</div>
</div>
<div class="footer ui inverted very padded vertical segment">
<div class="ui vertical segment">
<div class="ui four column grid">
<div class="column">
<h4 class="ui inverted header">About</h4>
<div class="ui inverted link list">
<a class="item" href="/stack">Stack</a>
<a class="item" href="/userale">UserALE</a>
<a class="item" href="/distill">Distill</a>
<a class="item" href="/tap">Tap</a>
<a class="item" href="/stout">Stout</a>
</div>
</div>
<div class="column">
<h4 class="ui inverted header">Docs</h4>
<div class="ui inverted link list">
<a class="item" href="/docs/stack">Stack</a>
<a class="item" href="/docs/userale">UserALE</a>
<a class="item" href="/docs/useralejs">UserAle.js</a>
<a class="item" href="/docs/useralepy">UserAle.py</a>
<a class="item" href="/docs/distill">Distill</a>
<a class="item" href="/docs/tap">Tap</a>
<a class="item" href="/docs/stout">Stout</a>
</div>
</div>
<div class="column">
<h4 class="ui inverted header">Community</h4>
<div class="ui inverted link list">
<a class="item" href="https://github.com/apache?q=flagon">GitHub</a>
<a class="item" href="http://stackoverflow.com/questions/tagged/apache-flagon">StackOverflow</a>
<a class="item" href="https://issues.apache.org/jira/browse/FLAGON">Jira Issue Tracker</a>
<a class="item" href="https://cwiki.apache.org/confluence/display/FLAGON">Project Wiki</a>
<a class="item" href="https://twitter.com/ApacheFlagon">Twitter</a>
</div>
</div>
<div class="column">
<h4 class="ui inverted header">Apache</h4>
<div class="ui inverted link list">
<a class="item" href="http://www.apache.org/">Apache Software Foundation</a>
<a class="item" href="http://www.apache.org/licenses/">License</a>
<a class="item" href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
<a class="item" href="http://www.apache.org/foundation/thanks.html">Thanks</a>
<a class="item" href="http://www.apache.org/security/">Security</a>
</div>
</div>
</div>
</div>
<div class="ui inverted vertical segment">
<div class="ui two column middle aligned grid">
<div class="column">
Apache Flagon is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.
</div>
<div class="center aligned column">
Copyright &copy; 2022 The Apache Software Foundation, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br>
Apache Flagon, Flagon, Apache, the Apache feather logo, the Apache Flagon logo and the Apache Incubator logo are trademarks of The Apache Software Foundation.
</div>
</div>
</div>
<div class="ui inverted vertical segment">
<div class="ui one column middle aligned grid">
<div class="center aligned column">
<a href="http://incubator.apache.org/">
<img src="/images/incubator-logo-white.jpg">
</a>&nbsp;
<a href="https://www.apache.org/events/current-event.html">
<img src="https://www.apache.org/events/current-event-234x60.png" alt="ASF Current Event">
</a>
</div>
</div>
</div>
</div>
</body>
</html>