DEV Community: Saleem

Let's visualize time-on-site captured with timeonsite.js using free "Visual tool" -part 2

Saleem — Thu, 08 Sep 2022 15:59:02 +0000

It is the continuation of the Let's build time-on-site counter for your website - Part 1 we wrote few weeks back. In the last article, we learnt about how to build a time-on-site counter to show in webpage and utilize timeonsite.js tracker to capture it in a modern and hassle-free approach. We also used state-of-the-art sendBeacon() JS API to save the critical user engagement data on page close. This is good! For each pageview, we get following data dynamically captured by timeonsite.js during page close

{
 TOSId: 1129620185532,
 TOSSessionKey: "14802525481391382263",
 TOSUserId: "anonymous",
 title: "Blog application — Nature & Wildlife",
 URL: "http://tos-localdata.london/home.php"
 entryTime: "2021–11–27 13:15:48.663",
 exitTime: "2021–11–27 13:17:31.663",
 timeOnPage: 103,
 timeOnSite: 103,
 timeOnPageTrackedBy: "second",
 timeOnPageByDuration: "0d 00h 01m 43s",
 timeOnSiteByDuration: "0d 00h 01m 43s",
 trackingType: "tos",
}

This record is great. But, how do we visualize all these data with large number of users spanned across millions of records? Let's say we have 1000 pageviews captured yesterday and we have an overall time-on-site of 185,300 seconds or 3088 minutes approximately as seen from "tos" table in the database.

"tos" table as in MariaDB/MySql DB

How many sessions occurred yesterday?
Which is the largest session that was captured yesterday?
Which is the smallest session or bounce-rate captured yesterday?
Which page (home, about or contact) got more attention in terms of user stay time?

One way is to query the data like this from our popular MariaDB or MySql DB as follows,

Total page views occurred on 2022-09-01

select count(tos_id) as Pageviews from tos WHERE entry_data like '%2022-09-01%'

Pageviews: 123

or to find a large session

Large session occurred in the website recently

SELECT 
  * 
FROM 
  tos 
WHERE 
  tos_session_key = (
    SELECT 
      tos_session_key 
    FROM 
      (
        SELECT 
          MAX(timeonsite) AS max_timeonsite, 
          tos_session_key 
        FROM 
          tos 
        GROUP BY 
          tos_session_key 
        ORDER BY 
          max_timeonsite DESC 
        LIMIT 
          1
      ) app_large_session
  ) 
ORDER BY 
  timeonsite DESC;

The result,

As you can see, 197 seconds or 3 mins 17 seconds is the large session occurred in tos table.

But, this is all custom querying to find our desired reports. Also, this is part of Timeonsite Analytics, an advanced querying technique to find insights and stats. We'll skip that for now. And let's take a look at the free tool "Visual" provided by timonsite.js for quick reporting and analytics view of the user engagement data.

Let's open the free Visual backend server and download it to your computer. If you just scroll down there, there are instructions for PHP/NodeJs. Let's take PHP since it's part of most popular LAMP stack along with MariaDB. I recommend you use XAMPP/WAMP/MAMP server if you are trying out this locally which provides you /www folder for quickly accessing PHP scripts. In our case, just download the visual into /www or /htdocs folder and follow the 5-minute installation given in Visual's repository page.

Now, you'll be able to access the Visual application at http://localhost/visual/index.html If you are trying out in cloud server, replace the localhost with your-website-com in this URL.

If you are going to use PHP, you can see that the Visual app is using PHP as default in this file

So, after uploading visual folder and making configurations properly like DB host, username & password, you will be able to see the reporting application. It'll be like this:

Key features to note (Data view)

It's built on usual JQuery DataTable
There is a search bar at the bottom of each column
You can copy paste any tos_session_key and put at the bottom of the page to understand how user came from page 1 to page 2 to page x to achieve "x" time-on-site data
"tos" column should be in ascending order. In case it's not in ascending order. Click on "up/down symbol" in column header to sort.
You can search by page titles alone
You can apply date filter at the top to view data for specific date or month. Apply "from" and "to" dates properly
Total records/pageviews can be seen at the bottom of the DataTable (Each record is a single pageview in website).
"Sync data" button can be clicked to fetch recent or real-time data occurring in your website.

There is a "Chart view" link at the top right side. Just click that to view analytics dashboard. It's high-level view of important stats of your website like time-spent duration, large sessions, recent sessions time duration etc. It's limited to recent 10k records. It is a configuration parameter in Visual app; you can customize it to large value if your browser and application support big load. Let's take a look at the analytics view of time-on-site data.

Let's take a look at key stats from this chart view:

Recent 75 sesssions by time-on-site

Page popularity table

As you can see, we'll be able to see how much engaged users are in our web application with recent sessions by duration and popular pages in our site.

Key features to note (Chart view)

It's built on popular charting library dc.js
Total occurrences is nothing but page views
You can also view anonymous vs authenticates users accessing the site.
There is a date-picker at the top to control the pageview/user engagement data by recent week or month, quarter or year.

Play around with this "visual" tool to learn more about it. You can customize anything in it and as much as you can since it's free reporting tool written in PHP/NodeJs. So, this tool is great for small, medium or large websites, personal blogging sites, beginners and site administrators to understand user engagement.

If you are looking for advanced reporting, try Timeonsite Analytics. Since you have user engagement data in table, you are not limited to SQL querying or Visual app reporting alone, the data can be visualized in any popular analytics tools like Tableau, Power BI, Qlik, Alteryx etc. You have got much more data projections, insights and stats there. I have a plan to write an article about time-on-site reporting on Tableau Public, free BI tool for you, later in the series.

Key points to note:

This reporting looks similar to other analytics tool on the surface but it's fetching not only pageviews from tracked data but also user's exact stay time on each page thanks to timeonsite.js' data accuracy consistency!

pageviews + stay time => "accurate user engagement"

If you have integrated timeonsite.js in your website/app with "callback" or "real-time" option, then you get "user engagement" for bounce rate pages as well. This is highly exclusive here since you won't get "user engagement" for bounce-rated pages in any other analytic providers except with difficult ping/poll techniques that they employ. This is the first time we have captured like this with the help of timeonsite.js and underlying beacon APIs.

timeonsite.js + callback option => "accurate user engagement for bounce-rated pages as well"

Try it out and let us know if there are any integration issues. Post it in comments. There are a good deal of posts online to support you. If you liked this article, go ahead and give a star on github repository.

Let's build a modern time-on-site counter for your website with timeonsite.js and JS Beacons

Saleem — Mon, 15 Aug 2022 12:45:49 +0000

Timeonsite.js can be used to measure most important metric for you website time-on-page and time-on-site. Though it can be calculated simply by finding the difference between page entry and page exit with Javascript's Date object, here we are going to use a powerful web implementation of this with the help of widely popular timeonsite.js library along with the help of sendBeacon() API for safe data persistence to DB table.

Basic HTML block



<!-- 
HTML page with "counter" div container 
-->
<html><head></head>
    <div id="counter">
    </div>
</html>

Javascript code snippet for building timer



// On page Load...
let entryTime = new Date();

//....
//User navigates the website
// some time later....

During Page exit....
let exitTime = new Date();

let timeSpent = exitTime - entryTime;
timeSpent = (timeSpent/1000); //convert to seconds

//Display the time spent with Jquery's API in page:
$(document).ready(function(){
    $('#counter').html('You have spent ' + timeSpent + 'seconds.');
});

That's it. We have measured user's time-on-page parameter nicely. But what about its accuracy, cross-browser compatibility and data persistence when user refreshes the page many times or opens N number of browser tabs of same website? What if user has gone to visit another shopping or social media website leaving the former webpage in open state?

Since timeSpent is a variable, it cannot control the states occurring in the webpage like inactive tab or multiple tabs opened concurrently for the same website. In this case, the accuracy of the timeSpent is lost and cannot be reliably measured. Let's take a look at the APIs exposed by timeonsite.js tracker.

But timeonsite tracker's Tos.getTimeOnPage() API exposes timeonpage data every time you call the API. And we are going to use this API to show and update our counter with timer data.



{
 TOSId: 1129620185532,
 TOSSessionKey: "14802525481391382263",
 TOSUserId: "anonymous",
 title: "Blog application — Nature & Wildlife",
 URL: "http://tos-localdata.london/home.php"
 entryTime: "2021–11–27 13:15:48.663",
 exitTime: "2021–11–27 13:17:31.663",
 timeOnPage: 103,
 timeOnSite: 103,
 timeOnPageTrackedBy: "second",
 timeOnPageByDuration: "0d 00h 01m 43s",
 timeOnSiteByDuration: "0d 00h 01m 43s",
 trackingType: "tos",
}

Step 1

Add the tracker snippet in your HTML page header



<head>
     <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/timeonsite/1.2.1/timeonsitetracker.js"></script>
</head>

Step 2

Add the Init code of the tracker



<script>
var config = {
    // track page by seconds. Default tracking is by milliseconds
    trackBy: 'seconds',
    callback: function(data) { /* callback denotes your data tracking is real-time */
        console.log(data);
        var endPointUrl = 'http://example.com' //Replace with your actual backend API URL http://localhost/tos
        if (data && data.trackingType) {
            if (data.trackingType == 'tos') {
                if (Tos.verifyData(data) != 'valid') {
                    console.log('Data abolished!');
                    return; 
                }
            }

            // make use of sendBeacon if this API is supported by your browser.
            if (navigator && typeof navigator.sendBeacon === 'function') {
                data.trasferredWith = 'sendBeacon';
                var blob = new Blob([JSON.stringify(data)], {type : 'application/json'});
                navigator.sendBeacon(endPointUrl, blob);
            }
        }
    }
};
var Tos;
if (TimeOnSiteTracker) {
    Tos = new TimeOnSiteTracker(config);
}
</script>

Step 3

Show the status of your time-on-page data in webpage as well



$(document).ready(function(){
    setInterval(function () {
        $('#counter').html('You have spent ' + Tos.getTimeOnPage().timeOnPage + 'seconds.');
    }, 1000); // Update the counter every second for real-time experience.
});

That's it. Watch for tracker imprint in browser terminal! We are done with accurate tracking of user's time-on-site in our website. There is a demo here if you want to see.

You will see counter like this. Customize the look.

Timeonsite.js will take care of everything like,

1, Inactive tabs
2, Data persistence on page refresh and reloads
3, Multiple tabs of same website (because in normal JS Date object, you will end up duplicate and wrong time-on-site data)
4, Saving data to your favorite DB table on page close. (You may use already backend visual, free backend server for saving this data in PHP/NodeJS)
5, Most importantly, unprecedented accuracy of the metrics ever captured by an analytics provider!

So, you can show how much time your users spent on your site and also you can show how much time user spent in last session as log taken from DB table.

In step 2, we used following lines,



navigator.sendBeacon(endPointUrl, blob);

This is one of the most powerful Javascript API for making HTTP post requests like XMLHTTPRequest but it works especially for retaining and saving log data during page close.

You'll see a ping in Network console unlike XHR/HTTP requests. I'm using a sample bin that causes CORS error. In normal app, it should send back success response.

Bonus point

Timeonsite.js also exposes a Tos.startActivity() API along with Tos.endActivity(). The advantage of this API is that it can track any specific activity in a site and it's bundled with same capabilities like time-on-page parameter like inactive tab, minimize tab or multiple tabs in measuring timing accuracy. Each pageview includes a TOSSessionKey to uniquely identify each activity ActivityId(TOSId) occurring in the site. Let's take an example,



// After initializing the TimeOnSiteTracker on page load, call startActivity() as
Tos.startActivity({applicantName: 'Nazir Khan'}); // this will start tracking the activity

// .
// .
// .
// after a while,

Tos.endActivity({applicantCountry: 'Romania'});
// calling .endActivity() will give back response

Gives response as,
{
    TOSId: 585872449448,
    TOSSessionKey: "14802525481391382263",
    TOSUserId: "anonymous",
    title: "Test application - TimeOnSiteTracker",
    URL: "http://tos-localdata.london/home.php",
    activityStart: "2021-11-27 13:20:46.707",
    activityEnd: "2021-11-27 13:20:50.213",
    timeTaken:4,
    timeTakenByDuration: "0d 00h 00m 04s"
    timeTakenTrackedBy: "second",
    trackingType: "activity",
    applicantName: "Nazir Khan",
    applicantCountry: "Romania"
}

If you liked this article, go ahead and give a star on github repository. And share your comments on how it's like to build your own time-on-site counter for your webpage.

Notes
This timeonsite.js is commercial library but it's also free for non-production sites and personal websites. So, let's use the free version hosted from CDN.js hosting website.