blob: 09601fe3b90fa91b535711cbd3664789756c52b8 [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>Modifying UserALE.js Source Code</title>
<meta name="description" content="Apache UserALE.js makes it easy for you to capture every user behavior on your webpage or application. But, you might not need all that data.">
<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/modifying/">
<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">Modifying UserALE.js Source Code</h2>
<p><a href="https://github.com/apache/incubator-flagon-useralejs">Apache UserALE.js</a> makes it easy for you to capture <em>every</em> user
behavior on your webpage or application. But, you might not need all that data.</p>
<p>UserALE.js also makes it easy for your to manage, and curate your logging scheme.</p>
<p>This guide walks you through how to modify UserALE.js log data and behavior through source code modification.</p>
<h2 id="modifying-useralejs-logs-via-source-code-modifications">Modifying UserALE.js Logs via Source Code Modifications</h2>
<p>We’re starting with this method because it will give context to others methods, like our script tag and API (below).</p>
<p>UserALE.js src is intuitively abstracted into few different files:</p>
<ul>
<li><a href="https://github.com/apache/incubator-flagon-useralejs/blob/master/src/attachHandlers.js">attachHandlers</a>: configure which user behaviors UserALE.js listens for and event handlers here.</li>
<li><a href="https://github.com/apache/incubator-flagon-useralejs/blob/master/src/configure.js">configure</a>: set special custom parameters, like passing a unqiue userID into UserALE.js logs.</li>
<li><a href="https://github.com/apache/incubator-flagon-useralejs/blob/master/src/getInitialSettings.js">getInitialSettings</a>: modify HTML5 parameters passed through the script tag.</li>
<li><a href="https://github.com/apache/incubator-flagon-useralejs/blob/master/src/main.js">main</a>: attaches event handlers and adds logs to queue (probably want to leave alone).</li>
<li><a href="https://github.com/apache/incubator-flagon-useralejs/blob/master/src/packageLogs.js">packageLogs</a>: modify to configure how user behaviors are added to data schema, and meta data added from the page.</li>
<li><a href="https://github.com/apache/incubator-flagon-useralejs/blob/master/src/sendLogs.js">sendLogs</a>: modify how logs are sent to logging server, etc. (be careful here, too).</li>
</ul>
<h3 id="usage">Usage</h3>
<p>Most modifications can be accomplished through <code class="highlighter-rouge">attachHandlers</code> and <code class="highlighter-rouge">packageLogs</code>.</p>
<p>Once you modify source, you’ll need to rebuild UserALE.js scripts and webextension (and should probably run unit tests).</p>
<h3 id="modifying-event-handlers-examples">Modifying Event Handlers: Examples</h3>
<p><code class="highlighter-rouge">attachHandlers</code> controls which behaviors and what kinds of logs are captured</p>
<p>You can modify some of the events UserALE.js by editing vars in <code class="highlighter-rouge">attacheHandlers</code>.</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">var</span> <span class="nx">events</span><span class="p">;</span>
<span class="kd">var</span> <span class="nx">bufferBools</span><span class="p">;</span>
<span class="kd">var</span> <span class="nx">bufferedEvents</span><span class="p">;</span>
<span class="cm">/* modify which events are abstracted into interval logs by editing the array below*/</span>
<span class="kd">var</span> <span class="nx">intervalEvents</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'click'</span><span class="p">,</span> <span class="s1">'focus'</span><span class="p">,</span> <span class="s1">'blur'</span><span class="p">,</span> <span class="s1">'input'</span><span class="p">,</span> <span class="s1">'change'</span><span class="p">,</span> <span class="s1">'mouseover'</span><span class="p">,</span> <span class="s1">'submit'</span><span class="p">];</span>
<span class="cm">/* modify which events are pulled from window*/</span>
<span class="kd">var</span> <span class="nx">windowEvents</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'load'</span><span class="p">,</span> <span class="s1">'blur'</span><span class="p">,</span> <span class="s1">'focus'</span><span class="p">];</span>
</code></pre></div></div>
<p>You can modify which events UserALE.js captures in it’s ‘raw’ log stream, by modifying the var <code class="highlighter-rouge">events</code>:</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cm">/* Comment out event types in the `events` var for granular modification of UserALE.js behavior */</span>
<span class="k">export</span> <span class="kd">function</span> <span class="nx">defineDetails</span><span class="p">(</span><span class="nx">config</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// Events list</span>
<span class="c1">// Keys are event types</span>
<span class="c1">// Values are functions that return details object if applicable</span>
<span class="nx">events</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">'click'</span> <span class="p">:</span> <span class="nx">extractMouseEvent</span><span class="p">,</span>
<span class="s1">'dblclick'</span> <span class="p">:</span> <span class="nx">extractMouseEvent</span><span class="p">,</span>
<span class="s1">'mousedown'</span> <span class="p">:</span> <span class="nx">extractMouseEvent</span><span class="p">,</span>
<span class="s1">'mouseup'</span> <span class="p">:</span> <span class="nx">extractMouseEvent</span><span class="p">,</span>
<span class="s1">'focus'</span> <span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="s1">'blur'</span> <span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="s1">'input'</span> <span class="p">:</span> <span class="nx">config</span><span class="p">.</span><span class="nx">logDetails</span> <span class="p">?</span> <span class="kd">function</span><span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="p">{</span> <span class="s1">'value'</span> <span class="p">:</span> <span class="nx">e</span><span class="p">.</span><span class="nx">target</span><span class="p">.</span><span class="nx">value</span> <span class="p">};</span> <span class="p">}</span> <span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="s1">'change'</span> <span class="p">:</span> <span class="nx">config</span><span class="p">.</span><span class="nx">logDetails</span> <span class="p">?</span> <span class="kd">function</span><span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="p">{</span> <span class="s1">'value'</span> <span class="p">:</span> <span class="nx">e</span><span class="p">.</span><span class="nx">target</span><span class="p">.</span><span class="nx">value</span> <span class="p">};</span> <span class="p">}</span> <span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="s1">'dragstart'</span> <span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="s1">'dragend'</span> <span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="s1">'drag'</span> <span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="s1">'drop'</span> <span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="s1">'keydown'</span> <span class="p">:</span> <span class="nx">config</span><span class="p">.</span><span class="nx">logDetails</span> <span class="p">?</span> <span class="kd">function</span><span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="p">...,</span>
<span class="cm">/*'mouseover' : null,*/</span> <span class="err">#</span><span class="nx">Aliasing</span> <span class="nx">the</span> <span class="s2">"events"</span> <span class="nx">list</span> <span class="nx">removes</span> <span class="nx">that</span> <span class="kd">class</span> <span class="k">from</span> <span class="nx">your</span> <span class="nx">event</span> <span class="nx">stream</span><span class="p">.</span>
<span class="s1">'submit'</span> <span class="p">:</span> <span class="kc">null</span>
</code></pre></div></div>
<p>You can eliminate the <code class="highlighter-rouge">interval</code> log stream altogether by modifying the <code class="highlighter-rouge">attachHandlers</code> configs:</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kd">function</span> <span class="nx">attachHandlers</span><span class="p">(</span><span class="nx">config</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">defineDetails</span><span class="p">(</span><span class="nx">config</span><span class="p">);</span>
<span class="nb">Object</span><span class="p">.</span><span class="nx">keys</span><span class="p">(</span><span class="nx">events</span><span class="p">).</span><span class="nx">forEach</span><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">ev</span><span class="p">)</span> <span class="p">{</span>
<span class="nb">document</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">(</span><span class="nx">ev</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">packageLog</span><span class="p">(</span><span class="nx">e</span><span class="p">,</span> <span class="nx">events</span><span class="p">[</span><span class="nx">ev</span><span class="p">]);</span>
<span class="p">},</span> <span class="kc">true</span><span class="p">);</span>
<span class="p">});</span>
<span class="cm">/*Comment out configs for intervalEvents to remove them from your log stream */</span>
<span class="nx">intervalEvents</span><span class="p">.</span><span class="nx">forEach</span><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">ev</span><span class="p">)</span> <span class="p">{</span>
<span class="nb">document</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">(</span><span class="nx">ev</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">packageIntervalLog</span><span class="p">(</span><span class="nx">e</span><span class="p">);</span>
<span class="p">},</span> <span class="kc">true</span><span class="p">);</span>
<span class="p">});</span>
</code></pre></div></div>
<h3 id="modifying-meta-data-packaged-in-logs-examples">Modifying Meta Data Packaged in Logs: Examples</h3>
<p><code class="highlighter-rouge">packageLogs</code> pulls parameters from the script tag, API, and from window or document and adds them to event logs.</p>
<p>The easiest way to make these changes is by modifying the var <code class="highlighter-rouge">log</code>:</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <span class="cm">/* Comment or add fields to be included in your logs*/</span>
<span class="kd">var</span> <span class="nx">log</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">'target'</span> <span class="p">:</span> <span class="nx">getSelector</span><span class="p">(</span><span class="nx">e</span><span class="p">.</span><span class="nx">target</span><span class="p">),</span>
<span class="s1">'path'</span> <span class="p">:</span> <span class="nx">buildPath</span><span class="p">(</span><span class="nx">e</span><span class="p">),</span>
<span class="s1">'pageUrl'</span><span class="p">:</span> <span class="nb">window</span><span class="p">.</span><span class="nx">location</span><span class="p">.</span><span class="nx">href</span><span class="p">,</span>
<span class="s1">'pageTitle'</span><span class="p">:</span> <span class="nb">document</span><span class="p">.</span><span class="nx">title</span><span class="p">,</span>
<span class="s1">'pageReferrer'</span><span class="p">:</span> <span class="nb">document</span><span class="p">.</span><span class="nx">referrer</span><span class="p">,</span>
<span class="s1">'clientTime'</span> <span class="p">:</span> <span class="nx">timeFields</span><span class="p">.</span><span class="nx">milli</span><span class="p">,</span>
<span class="s1">'microTime'</span> <span class="p">:</span> <span class="nx">timeFields</span><span class="p">.</span><span class="nx">micro</span><span class="p">,</span>
<span class="s1">'location'</span> <span class="p">:</span> <span class="nx">getLocation</span><span class="p">(</span><span class="nx">e</span><span class="p">),</span>
<span class="s1">'type'</span> <span class="p">:</span> <span class="nx">e</span><span class="p">.</span><span class="nx">type</span><span class="p">,</span>
<span class="s1">'logType'</span><span class="p">:</span> <span class="s1">'raw'</span><span class="p">,</span>
<span class="s1">'userAction'</span> <span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
<span class="s1">'details'</span> <span class="p">:</span> <span class="nx">details</span><span class="p">,</span>
<span class="s1">'userId'</span> <span class="p">:</span> <span class="nx">config</span><span class="p">.</span><span class="nx">userId</span><span class="p">,</span>
<span class="s1">'toolVersion'</span> <span class="p">:</span> <span class="nx">config</span><span class="p">.</span><span class="nx">version</span><span class="p">,</span>
<span class="s1">'toolName'</span> <span class="p">:</span> <span class="nx">config</span><span class="p">.</span><span class="nx">toolName</span><span class="p">,</span>
<span class="s1">'useraleVersion'</span><span class="p">:</span> <span class="nx">config</span><span class="p">.</span><span class="nx">useraleVersion</span><span class="p">,</span>
<span class="s1">'sessionID'</span><span class="p">:</span> <span class="nx">config</span><span class="p">.</span><span class="nx">sessionID</span>
<span class="p">};</span>
</code></pre></div></div>
<h3 id="benefits-modifying-useralejs-logs-via-src">Benefits Modifying UserALE.js Logs via src:</h3>
<ul>
<li>Full control of your log streams</li>
<li>With simple modification to src you can package and build multiple UserALE.js scripts for page-to-page modification
of log streams.</li>
<li>Modify the behavior of our webExtension</li>
<li>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.</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>