The implementation side of Palm Pre app measurement

I love mobile apps. They are my nearly con­stant com­pan­ions. At lunch, I can get caught up on the news I missed dur­ing the morn­ing. On the drive home from work, I get stream­ing music from all over the world (and, dur­ing the sum­mer, the live Red Sox radio feed I des­per­ately crave). And after work, I can tweet and e-mail as needed from wher­ever my fam­ily and I end up.

Ever since the iPhone App Store launched in July 2008, it seems that the bat­tle for the grow­ing smart­phone mar­ket has cen­tered largely on apps. As Apple and com­peti­tors release improved oper­at­ing sys­tems and dis­tri­b­u­tion lay­ers, organizations—likely includ­ing yours and those in your industry—will be quick to develop appli­ca­tions to run on them. In this crowded world, mea­sur­ing usage of your appli­ca­tion is key to the success.

With the new webOS by Palm, it is eas­ier than ever to imple­ment appli­ca­tion mea­sure­ment, so mea­sur­ing user inter­ac­tion is really straight­for­ward. In fact, my col­league, Jeff Minich, posted on this very topic last week and dis­cussed some of the awe­some things you can do with Palm Pre app mea­sure­ment, so I thought I’d tackle the imple­men­ta­tion side of the topic here. App devel­op­ment for webOS is done in JavaScript; tech­ni­cally, you could even use the stan­dard Site­Cat­a­lyst JavaScript library, just as you prob­a­bly do on your site, but here are some best prac­tices sug­gested and co-authored by Den­nis Wilkins, a mem­ber of the Omni­ture Engi­neer­ing team with sig­nif­i­cant expe­ri­ence build­ing mobile apps.

The first thing you want to do in set­ting up mea­sure­ment of your Palm Pre app is down­load the core Site­Cat­a­lyst JavaScript code from the Code Man­ager in the Admin Con­sole. (Since mobile apps are not the same as your web site, we rec­om­mend cre­at­ing a new report suite in the Admin Con­sole specif­i­cally for mea­sur­ing each mobile app.)

Cre­ate a folder in your project called “lib” and save that core track­ing code in there. I named my file s_code.js. Next in the sources.json file, in your project add this line of code to the array of sources.

{"source": "lib\/s_code.js"},


Now that you’ve done that, the s_code library can be called any­where in the appli­ca­tion. For sim­plic­ity, in this appinfo.json file in our project, we’ve added to the object a vari­able called “reportSuite:”

{
"id": "com.omniture.tracking",
"version": "1.0.0",
"vendor": "Omniture",
"type": "web",
"main": "index.html",
"title": "tracking",
"icon": "icon.png",
"reportSuite": "omniture.test"
}

You can also add any addi­tional sta­tic infor­ma­tion inside that file.

Now, in the app/assistants/stage-assistant.js file, we’ll add some sam­ple code to send a page view and instan­ti­ate a visit every time the appli­ca­tion is launched (stage-assistant.js will only be run once in basic webOS appli­ca­tions, and only when the appli­ca­tion is launched):

StageAssistant.prototype.sendTrackingCode = function()
{
var s_account = Mojo.Controller.appInfo.reportSuite; // grab the report suite out of the appinfo.json file
var s=s_gi(s_account);
s.pageName = "Application Launch"; // you could put any name here
s.channel = Mojo.Controller.appInfo.id; // add the application id (optional)
s.prop1 = "X"; // set a prop if you want to
s.t(); // send tracking code, and voila! you're done
}

Now in the Stage­As­sis­tant setup func­tion, we tell it to exe­cute that code:

StageAssistant.prototype.setup = function()
{
this.sendTrackingCode(); // do this first
this.controller.pushScene('first'); // push our first scene, or do any other logic as necessary
}

And that is how you could begin a sim­ple imple­men­ta­tion for the Palm Pre’s webOS. Not too tough, eh? Note that any other Site­Cat­a­lyst vari­ables can be set within the send­Track­ing­Code() func­tion, as necessary.

More advanced app mea­sure­ment isn’t much more dif­fi­cult. Here is some sam­ple code from our first scene. As you exam­ine this exam­ple, take none of the NDUID value; this ID is per­fect as a Site­Cat­a­lyst vis­i­tor ID, since it rep­re­sents the unique ID of the spe­cific Palm Pre run­ning the app. It will always be unique, and will never change, so it allows us to mea­sure how many time a spe­cific user has loaded the app or done a spe­cific action within the app. Below, we are also are set­ting the page­Name to the user’s cur­rent scene; you may want to append the appli­ca­tion name or some­thing else to the page name to bet­ter iden­tify it came from that app, if you are shar­ing the report suite with your web site or another appli­ca­tion. (Again, shar­ing a report suite with your web site or even other mobile apps is not typ­i­cally rec­om­mended. Cir­cum­stances may vary.)

FirstAssistant = Class.create({
user: false,

initialize: function(user)
{
this.user = user || {}; // assume I was passing around a user object to the scene when it was created. if it wasn't passed make it a blank object
},

setup: function()
{
this.startTrackingCodeChain(); // only fire tracking code when scene is created
},

activate: function(e)
{
// fire tracking code when the scene is activated, meaning that if a scene is pushed on 'this' and someone goes back it, will be fired a second time
//this.getUniqueIDThenSendTrackingCode();
},

deactivate: function(e)
{

},

cleanup: function(e)
{

},

// the reason why we are doing a tracking code chain is because the unique ID is obtained asynchronously
startTrackingCodeChain: function()
{
var nduid = Mojo.Model.Cookie('nduid'); // we could already have it, so store it
var uniqueID = nduid.get();
if (uniqueID) // if we do have it, fire the tracking code off with it; if we don't have it, do the asynch request to get it.
{
this.doTracking(uniqueID);
}
else
{
// this should only happen once per install, the cookie will remain as long as they have it installed
this.controller.serviceRequest('palm://com.palm.preferences/systemProperties', {
method:"Get",
parameters:{"key": "com.palm.properties.nduid" },
onSuccess: this.setUniqueID.bind(this) // here is the call back to do
}
});
}
},

setUniqueID: function(uniqueID)
{
var nduid = Mojo.Model.Cookie('nduid'); // once we have it, let's store it in the cookie so we don't have to get it ever again. . .
nduid.put(uniqueID); // storing the ID. . .
this.doTracking(uniqueID); // now send tracking code, finishing the chain
},

doTracking: function(uniqueID)
{
var s_account = Mojo.Controller.appInfo.reportSuite; // get the report suite our of appinfo.json
var s=s_gi(s_account);
s.pageName = this.controller.sceneName; //set the page name to the current scene's name (in this case its 'first')
s.visitorID = uniqueID; // use the devices id as visitorID.
s.prop1 = this.user.user_name || "Not logged in"; // we assumed the user object was passed in, so get the username, or, if it is false (or undefined), make it "not logged in"
s.t(); // fire tracking code
}
});

Of course, your app will have unique data points that you will want to mea­sure; this code is pro­vided as a basic exam­ple, but any data about your users or their expe­ri­ence that your app makes avail­able to you is free game for col­lec­tion in Site­Cat­a­lyst; all you will need to do is set Site­Cat­a­lyst vari­ables, likely the s.events vari­able, Cus­tom Traf­fic (s.prop) vari­ables, or Cus­tom Con­ver­sion (eVar) vari­ables to what­ever vari­ables in your app con­tain the data points you wish to track.

Ques­tions? Con­cerns? Applause? Please feel free to con­tact me by leav­ing a com­ment on this post, or via Twit­ter or Friend­Feed. I’d love to hear from you!