Tracking Custom Actions

Custom Actions are the most powerful tracking mechanism in Wide Angle Analytics. You have full control and flexibility to issue events on actions like:

• onchange - an HTML element has been changed,
• onclick - the user clicks an HTML element,
• onmouseover - the user moves the mouse over an HTML element,
• onmouseout - the user moves the mouse away from an HTML element, or
• onkeydown - the user pushes a keyboard key

And many more you will find documented here.

Configure Site

To enable able Custom Actions, first allow these in your site configuration.

Set-up JavaScript SDK

Add Wide Angle Analytics to your website using the late initialization option, and save a reference to the Wide Angle Analytics object.

Late initialization can be forced by adding data-waa-late-init="true" to the script tag.

The whole set-up code can look as follows:

<script 
  id="waa"
  src="https://stats.wideangle.co/script/1D1AG3B9ACA18F4247.js"     
  data-waa-late-init="true"
  defer
  async>
</script>

<script type="application/javascript">
  var waaScript = document.querySelector('#waa');
  waaScript.addEventListener('load', function() {
    waaCreate().then(waa => { window.waa = waa; });
  });
</script>

Sending an event

Using an example from the previous section, we can assume that your global JavaScript window instance holds a reference to waa, a Wide Angle Analytics object.

With that in mind, sending a custom action is as simple as a following JavaScript function call:

window.waa.dispatchEvent('<NAME>', {'<PARAM_NAME>': '<PARAM_VALUE>', ...}, {'VALUE_NAME': <VALUE>, ...});

The dispatchEvent accepts two parameters:

• name - a required name of the dispatched event; cannot contain spaces and must be composed of letters and numbers; maximum length of 128 characters; names starting with underscore are reserved for internal use and should be avoivded to prevent undefined behaviour,
• params - an optional object with key-value pairs containing additional information about the event; you can send up to three (3) parameters,
  • name - must be alpha-numeric string, only - and _ special characters are allowed; maximum length of 128 characters; parameter name type is reserved and should be avoided to avoid undefined behaviour,
  • value - accepts letters, numbers, basic punctuation (! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ \ { | } ~ ) signs and spaces; maximum length of 1024 characters.
• values - an optional object with key-value pairs containing numerical values,
  • name - must be alpha-numeric string, only - and _ special characters are allowed; maximum length of 128 characters; parameter name type is reserved and should be avoided to avoid undefined behaviour,
  • value - A number; can be a floating point number.

The dispatchEvent function returns a promise.

Let's build an example where we track an intent to purchase a monthly or annual plan based on where visitors place their mouse cursor.

<button 
   onmouseover="window.waa.dispatchEvent('buy-intent', {plan: 'monthly'}, {price: 10})"
   onclick="buyMonthly()">
    Buy Monthly
</button>

<button 
   onmouseover="window.waa.dispatchEvent('buy-intent', {plan: 'annual'}, {price: 100, items: 2})"
   onclick="buyAnnual()">
    Buy Annual
</button>

In closing

Custom actions allow for various activities and other user interactions to be tracked from JavaScript code.

Alternatively, you can use simpler and more structured Download and Click Action tracking.

Are you ready to view tracked events on your dashboard? Then, dive into setting Action Filters.