| <!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>UserALE.js API</title> |
| <meta name="description" content="Modifying UserALE.js Behavior via API"> |
| |
| <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.html"> |
| <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"> |
| Components |
| <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.html">UserALE.js Build and Test</a> |
| |
| <a class="item" href="/docs/useralejs/API.html">UserALE.js API</a> |
| |
| <a class="item" href="/docs/useralejs/modifying.html">Modifying UserALE.js</a> |
| |
| <a class="item" href="/docs/useralejs/dataschema.html">UserALE.js Data Schema</a> |
| |
| <a class="item" href="/docs/useralejs/troubleshooting.html">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">UserALE.js API</h2> |
| <h1 id="modifying-useralejs-behavior-via-api">Modifying UserALE.js Behavior via API</h1> |
| |
| <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 two functions: <code class="highlighter-rouge">setLogFilter</code> & <code class="highlighter-rouge">setLogMapper</code>. With these two powerful functions, you have a lot of lattitude in customizing and curating your logs.</p> |
| |
| <p>#API Usage</p> |
| |
| <p>To invoke the API, simply add additional javascript code blocks under your UserALE.js script tag.</p> |
| |
| <p>Don’t forget to add the UserALE.js script tag:</p> |
| <div class="language-html highlighter-rouge"><pre class="highlight"><code><span class="nt"><head></span> |
| <span class="nt"><title></span>UserAleJS - Example Page<span class="nt"></title></span> |
| <span class="c"><!-- |
| Add the UserALE.js script tag to the top of your doc |
| --></span> |
| <span class="nt"><script </span><span class="na">src=</span><span class="s">"/path/to/userale-1.0.0.min.js"</span> <span class="na">data-url=</span><span class="s">"http://yourLoggingUrl"</span><span class="nt">></script></span> |
| </code></pre> |
| </div> |
| |
| <p>##<code class="highlighter-rouge">setLogFilter</code> Examples</p> |
| |
| <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"><pre class="highlight"><code><span class="c"><!-- |
| Add additional code blocks to set the filters you want |
| This simple array filter pulls mouseover data out of your log stream |
| --></span> |
| <span class="nt"><script </span><span class="na">type=</span><span class="s">"text/javascript"</span><span class="nt">></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"></script></span> |
| </code></pre> |
| </div> |
| |
| <p>Here is one UserALE.js filter to rule them all!</p> |
| <div class="language-html highlighter-rouge"><pre class="highlight"><code><span class="c"><!-- |
| 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. |
| --></span> |
| <span class="nt"><script </span><span class="na">type=</span><span class="s">"text/javascript"</span><span class="nt">></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">&&</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"></script></span> |
| </code></pre> |
| </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-javascript highlighter-rouge"><pre class="highlight"><code> <span class="o"><</span><span class="nx">script</span> <span class="nx">type</span><span class="o">=</span><span class="s2">"text/javascript"</span><span class="o">></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="o"><</span><span class="sr">/script</span><span class="err">> |
| </span></code></pre> |
| </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"><pre class="highlight"><code><span class="c"><!-- |
| This will add your label to all event logs that reference a particular DOM target. |
| --></span> |
| <span class="nt"><script </span><span class="na">type=</span><span class="s">"text/javascript"</span><span class="nt">></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"></script></span> |
| </code></pre> |
| </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"><pre class="highlight"><code> <span class="nt"></head></span> |
| <span class="nt"><body></span> |
| <span class="nt"><div</span> <span class="na">id=</span><span class="s">"app"</span><span class="nt">></span> |
| <span class="nt"><button</span> <span class="na">id=</span><span class="s">"increment"</span><span class="nt">></span>+<span class="nt"></button></span> |
| <span class="nt"><button</span> <span class="na">id=</span><span class="s">"decrement"</span><span class="nt">></span>-<span class="nt"></button></span> |
| <span class="nt"><div</span> <span class="na">id=</span><span class="s">"scoreboard"</span><span class="nt">></div></span> |
| <span class="nt"></div></span> |
| <span class="nt"></script></span> |
| |
| <span class="nt"><script </span><span class="na">type=</span><span class="s">"text/javascript"</span><span class="nt">></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"></script></span> |
| <span class="nt"></body></span> |
| <span class="nt"></html></span> |
| |
| </code></pre> |
| </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> |
| |
| <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/useralejs">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://issues.apache.org/jira/browse/FLAGON">submit an issue report</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.</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 © 2019 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> |
| <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> |
