Google Analytics Upstream to PhoneGap

OPEN SOURCE / 04.21.15 / BlackBerry


Written by:  Tim Windsor

This is the third follow-up post from the UCOSP program this past fall. In previous terms, we started working on PhoneGap plugins to add BlackBerry 10 support. We started by building new BlackBerry 10 plugins, and then worked on merging them into the existing PhoneGap ones. Tanya, from the University of Alberta, worked on Google Analytics. Here’s her account of the term:

The first task I tackled this semester was to merge an existing BB10 plugin into the PhoneGap build repo. The plugin I merged was the Google Analytics (GA) plugin which is used to show who uses your application or website and how they use it. It tracks statistics for websites or applications such as downloads, page views, etc. Google Analytics supports Android and iOS, but not Blackberry. To use Google Analytics with Blackberry, the web tracking code was implemented. The plugin was coded in JavaScript and posts information to your Google Analytics account.

The first step I took to begin my task was to familiarize myself with JavaScript, as I was new to the language. To do this I spent time reading through the code for the plugin on GitHub and googling functions or anything I did not understand in the code. The ReadME files were also very helpful.

The first step in actually merging the plugin was to add the BB10 platform to the plugin.xml. This was a relatively straightforward task, which I worked on with one of my teammates, as she was also merging a different plugin into the PhoneGap repo.

Below is a description of all the BB10 plugin functions that I merged. Each function takes success and failure handlers as arguments as well as those detailed below.

To use the GA plugin users must first initialize the plugin with the function init() and send the GA account ID as an argument. This will be the property in your GA dashboard where the stats will be sent. Init also requires an argument used to determine the rate at which batches of logged metrics are sent to the GA account.

To log page views a function called trackPage() is used. This function takes as an argument the url of the page you wish to log.

The plugin also allows users to track events using the trackEvent() function. To use this function, it requires the category of the type of event, action, a label to describe the event, and a value whose meaning is up to the user of the plugin.

The function setVariable() sets a custom dimension. For a user to use this function, first they need to configure a custom dimension in their Google Analytics account. In their GA account they must define a custom dimension with an index, name and other properties. Next information is collected by calling the setVariable() function and sending the index defined in the account as an argument, as well as the value for the custom dimension. This information will be sent with the next function call. For example, if you call setVariable() and then trackEvent(), the value for the custom dimension will be sent with trackEvent().

Before exiting the app use exitGA() to check the queue and post any remaining information to the users GA account.

Overall, UCOSP has been a useful course allowing me to gain valuable real world experience. Having the opportunity to contribute to the Blackberry10 PhoneGap project has been insightful and helped me realize the importance of contributing to open source projects.

Since the work Tanya contributed, we’ve continued to work on the plugin and currently have a pull request open with the PhoneGap repo. Besides Google Analytics, she also performed preliminary investigation on the ExternalScreen plugin, which we started work on this term. If you’re interested in following along with the student project, watch #bbucosp on twitter. All of the code will be going into the public BlackBerry repositories on GitHub. If you want to get involved yourself, contact me to get started: @timothywindsor on twitter, on GitHub.


About BlackBerry

BlackBerry is an enterprise software and services company focused on securing and managing IoT endpoints.