atul-bhouraskar / timeme.js

A JavaScript library to accurately time how long a user views a web page

What is TimeMe.js?

TimeMe.js is a JavaScript library that accurately tracks how long users interact with a web page. TimeMe.js disregards time spent on a web page if the user minimizes the browser or switches to a different tab. This means a more accurate reflection of actual 'interaction' time by a user is being collected. Additionally, TimeMe.js disregards 'idle' time outs. If the user goes idle (no page mouse movement, no page keyboard input) for a customizable period of time, then TimeMe.js will automatically ignore this time. This means no time will be reported where a web page is open but the user isn't actually interacting with it (such as when they temporarily leave the computer). These components put together create a much more accurate representation of how long users are actually using a web page.

Furthermore - TimeMe tracks time usage across multiple pages. This is particularly useful when running a single page web application. You can get a list of all aggregate times spent on all pages from TimeMe.js.

Demo

You can see a demo of a timer using TimeMe.js here.

Where do I get TimeMe.js?

You can use Bower to install TimeMe (see next steps) and its dependencies. Alternatively, you can download the most recent copy at the TimeMe Github project. Notice you will also need a copy of Serkanyersen's ifvisible.js project. The ifvisible.js library is REQUIRED to allow TimeMe.js to work.

How do I use TimeMe.js?

First, obtain a copy of timeme.js and ifvisible.js. You can get both by installing TimeMe.js via Bower:

bower install timeme.js

Then, simply include the following lines of code in your page's head element:

<script src="ifvisible.js"></script>
<script src="timeme.js"></script">
<script type="text/javascript"">
	TimeMe.setIdleDurationInSeconds(30);
	TimeMe.setCurrentPageName("my-home-page");
	TimeMe.initialize();		
</script">

This code both imports the TimeMe.js library and initializes it. Notice that this code sets the idle duration to 30 seconds, which means 30 seconds of user inactivity (no mouse or keyboard usage on the page) will stop the timer. Also, we define a page name (my-home-page) to associate with the current timer.

Once imported and initialized, we can call the various methods made available by TimeMe.js. See the API documentation below for a complete breakdown of all of the available functionality. The most basic feature is to retrieve the time spent by the user on the current page:

var timeSpentOnPage = TimeMe.getTimeOnCurrentPageInSeconds();

In most cases you will want to store the time spent on a page for analytic purposes. You will therefore need to send the time spent on a page to the server at some point! When is the best time to do this? You can hook into the window.onbeforeunload event to do so. In most browsers this method is fired during a page's shut-down routine. Notice below that we use a synchronous request (not the usual asynchronous request) to guarantee the request to our server arrives before the page closes:

window.onbeforeunload = function (event) {
	xmlhttp=new XMLHttpRequest();
	xmlhttp.open("POST","ENTER_URL_HERE",false);
	xmlhttp.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
	var timeSpentOnPage = TimeMe.getTimeOnCurrentPageInSeconds();
	xmlhttp.send(timeSpentOnPage);
};

Using 'onbeforeunload' is by no means a requirement. You can hook into any other event or logical point in your application to send the time spent information to the server.

In a traditional web design where one static page is served for each request made by the client, any call to getTimeOnCurrentPageInSeconds() will be unique and valid for each page that imports and initializes TimeMe.js. Alternatively, if using a Single Page Application (SPA) design, TimeMe.js can have its timer stopped, page name switched, and the timer resumed (for the new page) with the following calls:

TimeMe.stopTimer();
// ... Now might be a good time to upload the time spent on the page to your server!
// ... load up new page
TimeMe.setCurrentPageName("new-page-name");
TimeMe.startTimer();

All page times are tracked in TimeMe.js, so you can review total aggregate time spent on each page for a particular user's session:

var timeSpentReport = TimeMe.getTimeOnAllPagesInSeconds();

This call will return an array of objects of page names and the corresponding aggregate time spent on that page.

What browsers are supported?

Chrome, Firefox, Safari, and IE 8+.

Anyone to give credit to?

TimeMe.js uses ifvisible.js. Take a look at serkanyersen's Github account if interested in just using the 'ifvisible' component of TimeMe that lets you know when a user is actively viewing your page!

API

TimeMe.setCurrentPageName(newPageName);

Sets the page name to be associated with any future calls to timer.

TimeMe.setIdleDurationInSeconds(durationInSeconds);

Sets the time (in seconds) that a user is idle before the timer is turned off. Set this value to -1 to disable idle time outs.

TimeMe.initialize();

Initializes the timer. Should only be called when first importing the library and beginning to time page usage.

var timeInSeconds = TimeMe.getTimeOnCurrentPageInSeconds();

Retrieves the time spent (in seconds) on the current page.

var timeInSeconds = TimeMe.getTimeOnPageInSeconds(pageName);

Retrieves the time spent (in seconds) on the indicated page.

var timeSpentInfo = TimeMe.getTimeOnAllPagesInSeconds();

Retrieves the time spent on all pages that have been recorded using TimeMe.js. Notice this only works for Single Page Applications (SPAs) where TimeMe.js is only initialized once.

TimeMe.startTimer();

Manually starts the timer for the current page. Notice this only works if the timer is currently stopped.

TimeMe.stopTimer();

Manually stops the timer. Notice this only works if the timer is currently running.

TimeMe.resetRecordedPageTime(pageName);

Clears the recorded time for the indicated page name.

TimeMe.resetAllRecordedPageTimes();

Clears all recorded times for all pages.