TimeMe.js is a JavaScript library that accurately tracks how long users interact with a web page. It 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. What is TimeMe.js?
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).
Furthermore - TimeMe supports tracking time for specific elements within a page. This means you can track and compare usage of different parts of the same web page. Multiple concurrent timers are supported.
These components put together create a much more accurate representation of how long users are actually using a web page.
You can see a demo of TimeMe.js Demohere.
First, obtain a copy of timeme.js. You can do so by pulling from our website or installing TimeMe.js via npm or Bower: How do I use TimeMe.js?
// http://timemejs.com/timeme.min.js
npm install timeme.js --save
bower install timeme.js
Then, simply include the following lines of code in your page's head element:
<script src="timeme.js"></script>
<script type="text/javascript">
TimeMe.initialize({
currentPageName: "my-home-page", // current page
idleTimeoutInSeconds: 30 // seconds
});
</script>
Notice that the 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.
Note: You can time any activity that you want, not just page time. Simply call the following code. TimeMe will automatically discount any idle or inactive time.
TimeMe.startTimer("my-activity");
// ... some time later
TimeMe.stopTimer("my-activity");
var timeOnActivity = TimeMe.getTimeOnPageInSeconds("my-activity")
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();
TimeMe.callAfterTimeElapsedInSeconds(15, function(){
console.log("The user has been using the page for 15 seconds! Let's prompt them with something.");
});
// Executes the first 5 times a user leaves the page TimeMe.callWhenUserLeaves(function(){ console.log("The user is not currently viewing the page!"); }, 5);
// Executes every time a user returns TimeMe.callWhenUserReturns(function(){ console.log("The user has come back!"); });
// Start tracking activity on element with id 'area-of-interest-1'
TimeMe.trackTimeOnElement('area-of-interest-1');
// some time later...
var timeSpentOnElement = TimeMe.getTimeOnElementInSeconds('area-of-interest-1');
What do I do with the time I've tracked?
In most cases you will want to store the time spent on a page for analytic purposes. You will likely need to send the time spent on a page to a back-end server.
TimeMe.js has websocket reporting built into it. Your page will establish a websocket connection with your websocket server. TimeMe will end the connection and report the user's time when the user leaves. Simply provide a few arguments to the initialize() method to enable it: Using WebSockets to send times
TimeMe.initialize({
currentPageName: "my-home-page", // current page
idleTimeoutInSeconds: 30, // seconds
websocketOptions: { // optional
websocketHost: "ws://your_host:your_port",
appId: "insert-your-made-up-app-id"
}
});
Alternatively you can issue an HTTP request to your back end server to report time. Note: the following example sends an HTTP request during the the window.onbeforeunload event. This approach may not work in all browsers as there is no guarantee that the request will complete before the browser terminates it. Using standard http requests to send time
window.onbeforeunload = function (event) {
xmlhttp=new XMLHttpRequest();
xmlhttp.open("POST","ENTER_URL_HERE", true);
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.
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.
All major desktop and mobile browsers. What browsers are supported?
You'll need to install QUnit, which should be packaged with TimeMe.js if you performed a Bower install of TimeMe.js. Once you have installed QUnit, you can simply open the test files to execute the tests. How do I run the unit tests?
API
TimeMe.initialize(options);
// options.currentPageName // - Name of the page (home, about, etc.)
// options.idleTimeoutInSeconds // - how much inactive time before user considered idle
// options.websocketOptions: { // Turn on websocket reporting
// websocketHost: "ws://your_host:your_port",
// appId: "insert-your-made-up-app-id"
// }
var timeInSeconds = TimeMe.getTimeOnCurrentPageInSeconds();
var timeInSeconds = TimeMe.getTimeOnPageInSeconds(pageName);
TimeMe.callAfterTimeElapsedInSeconds(timeInSeconds, callback);
TimeMe.callWhenUserLeaves(callback, [[numberOfInvocations]]);
TimeMe.callWhenUserReturns(callback, [[numberOfInvocations]]);
TimeMe.trackTimeOnElement(elementId);
TimeMe.getTimeOnElementInSeconds(elementId);
TimeMe.setCurrentPageName(newPageName);
TimeMe.setIdleDurationInSeconds(durationInSeconds);
var timeSpentInfo = TimeMe.getTimeOnAllPagesInSeconds();
TimeMe.startTimer();
TimeMe.stopTimer();
TimeMe.resetRecordedPageTime(pageName);
TimeMe.resetAllRecordedPageTimes();
To minify the code, run the following: Build Tools
npm install uglify-js -g
uglifyjs timeme.js --mangle --compress --support-ie8 --output timeme.min.js