Gadget Usage Stats

Introduction

One of the most rewarding parts of making a gadget is seeing that people use it and send feedback. Detailed statistics about the gadget usage combined with the feedback will help you make improvements in the right direction. This article will show you how to fetch usage stats (like number of users, session lengths, etc.) and when it's ok to do it keeping in mind the privacy of the user.

Information Flow

The easiest way to understand the stat fetching process is to break it down into steps. For example, you can take a look at the diagram below:

Database

Server-side Script

As i've said, we need a server-side script which can be called by gadgets with certain parameters and which can, in turn, connect to the database and insert an entry in the table. In this example, we'll use PHP (check out the comments for details):

<?php

	//----VARIABLE PART OF THE PHP
	//location of the database host (given by providers):
	$dbhost = '_THE_HOST_';
	//username with which to log in the database:
	$dbuser = '_USERNAME_';
	//password:
	$dbpass = '_PASSWORD_';
	//database name:
	$dbname = 'web_tv_radio_stats';
	//insertion query into the right table, using the parameters which the PHP receives
	$dbquery = "INSERT INTO `Actions` (Action,Parameters,Moment) VALUES ".$_POST['Action']."','".$_POST['Parameters']."','NOW()')";

	//----CONSTANT PART OF THE PHP 
	//connecting to the database:
	$conn = mysql_connect($dbhost, $dbuser, $dbpass);
	mysql_select_db($dbname);
	//running the query:
	mysql_query($dbquery);
	//closing the database:
	mysql_close($conn);
	//optional return message:
	echo 'finished';
 ?>

So basically, you connect to the database, you run the query and then you close the database:

Initiating the Process within the Gadget

We acknowledged 2 aspects that can be of interest to us: how many people install the gadget and how long they keep it. In the case of these 2 issues, we can automatically send the messages to the PHP when the gadget is opened:

function _onOpen(){

	//setting default options
	//...
	options.putDefaultValue("firstInstall",true);
	options.putDefaultValue("UID",new Date().getTime());

	//getting a confirmation, and, if it's the case, an install notification
	var f=new Fetcher();
	if (options.getValue("firstInstall")){
		options.putValue("firstInstall",false);
		f.post(parameters.WebTvCentral,"install",parameters.version);
	}
	f.post(parameters.WebTvCentral,"confirm",options.getValue("UID"));
}

Notice how we get a unique ID, through the Date's object getTime() function which returns the number of milliseconds passed since 1970. :-) Keep in mind that this is not actually an ID, it's a key which allows us to group the confirmation messages and measure time lengths; everything is still perfectly anonymous. Extra actions which are triggered by users (like settings, feature use, etc.) should be fetched only with explicit permission; this can easily be done using a checkbox in the options dialog.

You might be wondering what exactly the Fetcher object is. I called it that way because it allowed me to fetch usage stats from a remote database (the object basically calls the PHP). Its implementation is below:

function Fetcher(){
}

//...

Fetcher.prototype.post=function(URL,Action,Parameters){

	try{ 
		var xmlObject = new XMLHttpRequest(); 
	} 
	catch (error){
		var xmlObject = new ActiveXObject("Microsoft.XMLHTTP");
	}

	//setting up the parameters:
	params="Action="+Action+"&Parameters="+Parameters;
	xmlObject.open("POST",URL,true);
	xmlObject.setRequestHeader('Content-type','application/x-www-form-urlencoded');
	//xmlObject.setRequestHeader("Content-length", params.length);
	//xmlObject.setRequestHeader("Connection", "close");
	xmlObject.send(params);
}

Conclusion

There we have it! A perfectly flexible and expandable usage stats system to help us measure the evolution of a gadget.

Resources

Author Bio