Using Google Universal Analytics with PhoneGap Apps

July 16, 2013Joe Christopher

We come across unique analytics tracking issues all of the time at Blast.

These range from advanced widget/tool tracking to very detailed data collection for inline listings on a website. Our technical team has encountered many unique situations and we absolutely love the challenge when we take on work that pushes the limits of Google Analytics, and we are able to build a solution that provides value to our clients.

Below is one such unique request that we recently received. We provided a solution for getting mobile app tracking on the PhoneGap framework to work correctly in Universal Analytics.

PhoneGap by Adobe is a framework that allows you to build apps using web technologies (html, css, and javascript) and then build them across many mobile platforms.

It is a great way to build mobile apps where you just need to code it once and easily build across seven mobile platforms (currently iOS, Android, Windows Phone 7/8, Blackberry OS, WebOS, Symbian, and Bada).

Tracking usage of your mobile apps is critical to understanding usage patterns and if users are doing what you want them to do. Google Analytics is a great platform for this.

Prior to Google’s Universal Analytics measurement protocol, you were forced to use a plugin for PhoneGap to get data into Classic Google Analytics. This works well, but you can’t take advantage of the new Universal Analytics features like custom dimensions and metrics (and more).

Unfortunately, if you attempt to use Universal Analytics with PhoneGap, you’ll run into a few issues that will prevent it from working. In this blog post, we review the issues and the solution to get Universal Analytics working with PhoneGap mobile apps.

The Challenge

Don’t attempt to use the Mobile App tracking code that Google provides. This code is for when you’ll be coding in native iOS or Android programming languages (Objective-C and Java). Since PhoneGap essentially is rendering a local web page, you should be using the web tracking analytics.js code.

When you use analytics.js, it is assuming that you are loading your web page from an http or https (ssl) protocol. PhoneGap renders pages via the file:// protocol. This is going to cause problems in a few areas. You can’t store cookies with the file:// protocol since there is no domain and the location of the analytics.js file is a relative protocol, which results in the file not being found.

Additionally, there is a bug in version 2.5.0 of PhoneGap that causes an Type Error on iOS. We provide a fix for that here as well.

Custom 4 Step Solution

To get around the file:// protocol issue, we need to do four things.

1) Modify the analytics.js file to remove the code that aborts itself when it doesn’t see either the http or https protocol. If we take the http://www.google-analytics.com/analytics.js file into jsbeautifier.org to make it easier to edit, we have to locate the Oa() function and comment out a line. Note that when Google updates analytics.js, this function may no longer be called Oa() due to changes when they re-compress the file. Here’s the code; comment out the if statement on line 248.

2) In PhoneGap v2.5.0 (fixed in later versions), there is a Type Error in iOS when analytics.js executes. This is an issue with navigator.javaEnabled. To fix, comment out line 814:

3) Since you’ve just made edits to analytics.js, you’ll want to host this file locally as part of your PhoneGap build file. Here’s the snippet you should use to reference an analytics.js file that you now host locally in the root folder of the application:

Note: If Google in the future adjusts analytics.js to work correctly, you’ll still need to adjust the code snippet above since it is currently relying on a relative protocol.

4) You can’t store cookies when using the file:// protocol. There is no domain to store the data with. So, we need to instead turn off cookie storage in Universal Analytics and instead pass in our own clientId value. Here’s where you have an option. You have the following options to consider:

• You can use the device.uuid API in PhoneGap to grab a UUID

   ga('create', 'UA-XXXXXX-YY', {
   'storage': 'none',
   'clientId':device.uuid
   });
   ga('send', 'pageview', {'page': '/my/page'});

• You can set your own clientId value if your users are logged in. Google recommends a UUID v4 value.

  ga('create', 'UA-XXXXXX-YY', {
  'storage': 'none',
   'clientId':'92bf24a5-20e5-4181-9778-2835f28c52d8'
   });
   ga('send', 'pageview', {'page': '/my/page'});

• You could generate a random one and implement logic to store it in localStorage of the browser. (code not shown for this option)

By following the above steps, you’ll have PhoneGap mobile app tracking in place that works with Universal Analytics. If you want to test this out, I’ve created a really simple application that you can compile and reference (hosted on GitHub).

About the Author

Joe Christopher

As Vice President of Analytics at Blast Analytics, Joe leads a team of talented analytics consultants responsible for helping clients understand and take action on their vast amounts of data, to continuously improve and EVOLVE their organizations. With over 20 years of experience in analytics and digital marketing, Joe offers a high-level of knowledge and guidance to clients across all industries. He is an expert in all major analytics platforms including Google Analytics and Adobe Analytics, as well as various tag management systems such as Tealium and Adobe Launch. He also consults on data visualization, data governance, and data quality strategies. Having extensive expertise in many areas, has enabled Joe to become a well known thought leader and speak at industry events such as Tealium’s Digital Velocity series. Joe remains on the pulse of various information technology, programming languages, tools and services, keeping Blast and its clients on the leading edge.

Connect with Joe on LinkedIn. Joe Christopher has written 51 posts on the Blast Digital Customer Experience and Analytics Blog.