Validate Your Mobile App Measurement Implementation

I’ve had a num­ber of ques­tions recently from cus­tomers ask­ing how to val­i­date mobile appli­ca­tion ana­lyt­ics imple­mented using Omni­ture App Mea­sure­ment Libraries. Depend­ing on the sit­u­a­tion, there are a num­ber of meth­ods which can be used to val­i­date and debug ana­lytic imple­men­ta­tions in native mobile apps. The details in this post are fairly tech­ni­cal so if you’re not the per­son respon­si­ble for val­i­dat­ing your app ana­lyt­ics, you should pass on the fol­low­ing details to the lead respon­si­ble for validation.

Four com­mon meth­ods for cap­tur­ing ana­lyt­ics requests from mobile apps were con­tributed for this post by Shawn Austin [Client­Care], Sam Kut­tler [Client­Care], and Carl Sandquist [Omni­ture Con­sult­ing Services]:

Sim­u­la­tor

Requests trig­gered by App Mea­sure­ment libraries can be exam­ined from within the devel­op­ment or sim­u­la­tor envi­ron­ment. The fol­low­ing exam­ple uses syn­tax spe­cific to the iPhone but the method­ol­ogy is very sim­i­lar for Android, Black­berry, and Symbian.

Pros: Debug­ging inte­grated within the devel­op­ment envi­ron­ment
Cons: Requires source code and famil­iar­ity with native code

1. Place track­ing code appro­pri­ately within the iPhone appli­ca­tion (as described in the App­Mea­sure­ment for iPhone imple­men­ta­tion guide). Since debug­ging out­put needs to be exposed to the devel­op­ment work­sta­tion, you will link to the libOmnitureAppMeasurement-iPhoneSimulator.a library (as opposed to the libOmnitureAppMeasurement-iPhoneDevice.a).
2. Enable debug­Track­ing (debug­Track­ing = YES). Typ­i­cally this is done after the “s” instance has been declared. Here’s an exam­ple:
   

   - (void)applicationDidFinishLaunching:(UIApplication *)appli­ca­tion {
   OMApp­Mea­sure­ment * s = [OMApp­Mea­sure­ment getInstance];
   s.account = @“reportsuite”;
   s.debugTracking = YES; //prints debug requests in con­sole
   s.pageName = @“iPhone App Test”;
   s.dc = @“122”;
   [s track];
   }

3. Save the file.
4. Within the Xcode appli­ca­tion open the Con­sole win­dow (Run > Console).
5. Run the iPhone Appli­ca­tion (Run > Run)—the iPhone Sim­u­la­tor should launch. HTTP requests to Omni­ture should appear within the Con­sole win­dow as appro­pri­ate actions (per the coder’s design) are taken within the iPhone application.

[update] Note: you can val­i­date requests on an actual device by com­pil­ing and run­ning the appli­ca­tion on a device con­nected to your devel­op­ment machine. Requests may be viewed in the console.

Proxy Server

By con­fig­ur­ing WiFi proxy set­tings on your mobile device and using a packet snif­fer on another com­puter attached to the same net­work, you can watch http/https requests made by the appli­ca­tion, includ­ing requests sent by the App Mea­sure­ment libraries.

Pros: Quick to set up, exposes mea­sure­ment behav­ior on actual device
Cons: May not work for all net­work con­fig­u­ra­tions (e.g. WiFi and LAN must be on same sub­net), not all mobile devices sup­port proxy set­tings (e.g. older ver­sions of Android).

1. Down­load and install soft­ware with packet sniff­ing and proxy server capa­bil­i­ties. Our exam­ple below demon­strates Charles but a num­ber of other soft­ware pack­ages are avail­able with sim­i­lar functionality.
2. Con­nect your mobile device and your work­sta­tion to the same WiFi net­work. You may want to dis­able the “mobile net­work” radio to ensure your mobile device is con­nect­ing exclu­sively through WiFi.
3. Deter­mine your computer’s IP address on the local net­work. This can be done on a win­dows machine by choos­ing Start > Run > type in “cmd”, click OK (a com­mand win­dow should pop up), type ’ ipcon­fig’ at the com­mand prompt and hit Enter—resulting out­put includes your computer’s IP Address
4. Open Charles, choose Proxy > Proxy Set­tings and make sure “Enable trans­par­ent HTTP prox­y­ing” is checked. You should also note the port (8888 in this case).



5. Con­fig­ure proxy set­tings on your mobile device to use the same IP address as your desk­top and the same port set in Charles. To per­form these steps on the iPhone:
   1. Go to Set­tings > Wi-Fi and tap the blue arrow next to your WiFi connection.
   2. Scroll to the bot­tom of the WiFi Con­nec­tion set­tings and tap “Man­ual” under HTTP Proxy.
   3. Type in your computer’s IP address for the Server (as recorded in Step 3) and port spec­i­fied in Charles (8888 in this case). When you are done it should look some­thing like the following:



6. Launch the appli­ca­tion you wish to val­i­date or debug—you should see pack­ets appear­ing in Charles from your mobile device.

Note: If you need to exam­ine mea­sure­ment for secure requests, fol­low these instruc­tions for sniff­ing secure pack­ets.

Vir­tual WiFi Access Point

Turn your desk­top into a Wi-Fi Access Point using the wire­less card to cre­ate the hot spot and the hard-wired con­nec­tion for inter­net access. Once your mobile device con­nects to the WiFi Access point, you can mon­i­tor the inter­net traf­fic going through your desk­top using a net­work packet sniff­ing utility.

Pros: Easy to set up, works for any mobile device that can con­nect via WiFi
Cons: Hard­ware require­ments (need a PC with Win­dows 7 or a Mac), requires com­puter with both WiFi and LAN

Cre­ate WiFi Access Point in Win­dows 7:

1. Down­load and install soft­ware with WiFi shar­ing capa­bil­i­ties. Our exam­ple below demon­strates Con­nec­tify but a num­ber of other solu­tions are also avail­able. Con­nec­tify sup­ports most wire­less cards but you may wish to ver­ify your card will work prior to the install. The­o­ret­i­cally, con­nec­tion shar­ing can be done with­out addi­tional soft­ware like Con­nec­tify in XP or Win­dows 7 by con­fig­ur­ing a Wire­less Net­work Con­nec­tion; how­ever, in prac­tice the con­nec­tion tends to be very flaky if it works at all.
2. Con­fig­ure a new wire­less con­nec­tion in Connectify—you’ll need to spec­ify the net­work name (“Wi-Fi Name”) and pass­word, choose “Access Point” for the Mode, and choose “Local Area Con­nec­tion” (the hard-wired inter­net con­nec­tion) for “Inter­net”. If you don’t have “Access Point” as an avail­able option, then your wire­less card is prob­a­bly not sup­ported by Connectify.
3. Once your set­tings have been spec­i­fied, choose the “Start Hotspot” option, and your net­work should be cre­ated and become vis­i­ble to the mobile device within a few seconds.

Cre­ate WiFi Access Point in Mac OS X:

1. Enable “Inter­net Shar­ing” in order to broad­cast as a Wi-Fi net­work and become vis­i­ble to the mobile device. Go to Sys­tem Pref­er­ences -> Shar­ing and choose “Inter­net Shar­ing” (but don’t actu­ally check the box yet), then click the “Air­Port Options” but­ton in the lower right:



2. Select a net­work name and choose a pass­word (this will be the net­work that we will con­nect the mobile device to):



3. Click “OK” to return to the pre­vi­ous win­dow. Select the check­box next to “Inter­net Shar­ing” to acti­vate the new net­work. You should see “Inter­net Shar­ing: On” like in the image below:

Con­fig­ure Net­work Packet Sniff­ing Utility:

1. Now the WiFi net­work is set up, con­fig­ure your mobile device to con­nect to this new Access Point. Select the new net­work from the list of avail­able net­works on the mobile device and then enter in the pass­word used when con­fig­ur­ing the net­work. You can ver­ify inter­net is work­ing on the mobile device by brows­ing the web.
2. Next, we’ll need to down­load and install a net­work packet sniff­ing util­ity. The fol­low­ing exam­ple uses Wire­shark. In Win­dows 7, the install was straight­for­ward and Wire­shark worked the first time I opened it. The Mac ver­sion of Wire­shark was not as easy to install (Wire­shark did not rec­og­nize any of my net­work inter­faces at first). If you are doing a Mac install of Wire­shark, be sure to first read and fol­low the direc­tions in the “Read Me First” text file (that comes bun­dled with the down­load). Once those changes had been made, fur­ther con­fig­u­ra­tion still had to be com­pleted (see this guide); but ulti­mately I was able to get Wire­shark installed on MAC.
3. Open Wire­shark. On the ini­tial screen, choose “Cap­ture Options”, or the menu item Cap­ture -> Options.
4. For the “Inter­face”, choose your wire­less net­work adapter. Also, make sure the promis­cu­ous mode check­box is enabled. Click “Start”:



5. You should now see a screen con­tain­ing all Net­work Traf­fic pass­ing through the wire­less adapter. To iso­late just the Omni­ture requests, add the fol­low­ing Fil­ter: http.request.uri con­tains “/b/ss/”.



6. As the screen­shot shows, the fil­ter now dis­plays only Omni­ture packets.

Hub

If none of the above meth­ods work for you, you can mod­ify your net­work con­fig­u­ra­tion by adding a hub to pro­vide vis­i­bil­ity to all the requests sent on the sub­net below the hub.

Pros: Allows vis­i­bil­ity into net­work requests when other meth­ods can’t be used
Cons: May need to pur­chase a hub (for this exam­ple, a dynax DX-EHB4 was pur­chased from Best­Buy for $25 USD)

1. Add a hub to your wire­less net­work. The com­puter you will be using to mon­i­tor requests and the wire­less router your mobile device will be using to con­nect over WiFi should both be plugged into the hub.
2. Fol­low the instruc­tions above to set up and con­fig­ure Net­work Packet Sniff­ing Utility.

Note: if the hub method doesn’t work in your sit­u­a­tion, Wire­shark has doc­u­mented a num­ber of addi­tional Eth­er­net packet cap­ture con­fig­u­ra­tions.

I can see the Omni­ture requests, now what?

Now you’re able to see the ana­lyt­ics requests, you’ll want to val­i­date mea­sure­ment is occur­ring at key usage mile­stones (e.g. app launch, screen view, etc.) and that the proper vari­ables are set at these mile­stones. As you review the requests, you’ll want to ref­er­ence one of the man­u­als below which map query para­me­ters back to Omni­ture variables:

• Site­Cat­a­lyst > Help > Sup­port­ing Docs > Man­u­als > Site­Cat­a­lyst Imple­men­ta­tion (sec­tion 6.1.3 and 6.1.4)
• Site­Cat­a­lyst > Help > Sup­port­ing Docs > Man­u­als > Mobile Device Mea­sure­ment (sec­tion A.5)