The actions API allows the creation of discrete notifications or events that are attributed to action types that impart meaning upon them. By creating actions of different action types it becomes possible to draw on some insights from the analytics provided in the EVRYTHNG Dashboard. In addition, actions have customFields, allowing you to add any additional data about the user's behaviour, page location, or errors encountered that may also be required.
This walkthrough will demonstrate a simple use-case of actions and action types - instrumenting a web page or web application to record the frequency of different kinds of user interaction:
- When a page is loaded.
- When a button is pressed (that does not cause the browser to navigate away)
- When an error occurs.
- Some other kind of page interaction not concerned with navigation.
To help implement this kind of application of actions as quickly as possible, we will provide a compressed script for you to add to the web page or application to be instrumented.
Getting Started
The instrumentation will consist of the following process:
- Create an anonymous Application User to represent the visitor.
- Record an action of type
_PageVisited, including the domain URL visited. - Make available a function
createAction()that can be used to create an action at any other point.
In order to create an Application User, you must first create a project and application using either the Dashboard or API. Once this is done, make a note of the Application API Key (not the Trusted Application API Key) for use later on.
Finally, create the _PageVisited action type if it does not already exist (using either the Dashboard or API), as well as any other types you will use in instrumenting your web page. For example: _VideoWatched, _UserLogin, or _BasketCleared. Make sure these action types are scoped to the same project that was just created, or they will not be available for the anonymous Application User to use.
Drop-in Snippet
The following snippet should be placed as-is in to the <body> of the web page(s) to be instrumented, with only the following minor modification:
- Replace
$APPLICATION_API_KEYwith the Application API Key you noted earlier.
<script type="text/javascript">
!function(){function e(e,n,t,i){var o=new XMLHttpRequest;o.open("POST","https://api.evrythng.com"+e,!0),o.setRequestHeader("Content-Type","application/json"),o.setRequestHeader("Authorization",n),o.onload=function(){i(o.response)},o.send(JSON.stringify(t))}e("/auth/evrythng/users?anonymous=true","$APPLICATION_API_KEY",{anonymous:!0},function(n){var t=JSON.parse(n).evrythngApiKey,i={type:"_PageVisited",customFields:{url:window.location.href}};e("/actions/_PageVisited",t,i,function(){}),window.createAction=function(n,i={}){e("/actions/"+n,t,{type:n,customFields:i},function(){})}})}();
</script>Once the browser loads this snippet, three things will occur:
- An anonymous Application User is created, and their Application User API Key remembered.
- An action of type
_PageVisitedis created, with the currentwindow.location.hrefincluded incustomFields. - A function
createAction()is attached to thewindowobject.
To create the additional actions to _PageVisited, such as the examples mentioned before, use the createAction() function at the appropriate time. For example, in a button's click handler:
const loginButton = document.getElementById('button_login');
loginButton.addEventListener('click', (e) => {
const userIdField = document.getElementById('input_userId');
const userId = userIdField.value;
// Create an action including the user Id who logged in
createAction('_UserLogin', { user: userId });
});Results
In this way, many different types of user interaction or event can be tracked anonymously, and the data shown on appropriately configured Dashboard widgets. An example is shown below:
