Blog

Top

  • PhoneGap-alytics

    by Jesse | Wed, May 4, 2011

    Do you want to gain marketing intelligence and information on how users interact with your PhoneGap app? You need this plugin!


    Introducing the Google Analytics for PhoneGap plugin.


    Over the last couple weeks, Joe aka @infil00p and I have been working on some exciting new plugins. We wanted to provide a simple way for PhoneGap developers to get analytics data on the usage of their apps.
    Instead of doing something silly [edit: removed prickish link], like trying to write our own analytics engine, we integrated with Google’s best in class offering.


    But PhoneGap apps are webpages already, can’t I just include the script tag for web sites?


    Yes, you could, in fact, if you are targeting BlackBerry, Palm or other devices, you will need to do this. For iOS and Android though, this plugin allows analytics data to be stored when the application is running without a network connection, and updated when a network becomes available. You could even track the fact that the network is unavailable, so you can compare metrics of offline vs online usage.


    Building the plugin


    Google already provides code for Android and iOS, so we really just needed to make a mapping from the JS side to the native side. Phonegap’s pluggable architecture made this simple, as this is exactly what it was built to do. We simply reviewed the Google SDK functionality and mirrored this in JS.



    Google’s GANTracker class provides the bulk of the functionality and exposes the following methods:

    startTrackerWithAccountID

    • given a web-entity-id, start tracking engine.
    • the engine will periodically send analytics data to the server.
    • the engine will cache data if there is no network connection, and update the server when it can.

    trackEvent

    • parameters for category, action, label, value
    • when something happens in your app, and you want to keep track of it, you can call trackEvent
    • google has an in-depth guide to using custom events here

    trackPageview

    • pageViews mean something different in an application, they may reflect actual pages, or perhaps different views within your app.
    • The choice of what you send for pageUri is up to you. It can be any string value, for example /application/launch or app/settings.


    Installation and Use


    To setup Android, you will need to follow Google’s instructions in the docs.
    For iOS, I have packaged the lib and header, so you can simply add everything in the iOS folder of the repo.

    From finder, place the plugin js file in your www folder, and include it in the page.
    After receiving the deviceready event in your app, start the tracker.
    Note that I create a local alias, so I don’t need to type window.plugins.googleAnalyticsPlugin everywhere, and code can be more readable.
    This gist demonstrates the initialization, and shows how to track the fact that your app was launched, as well as showing an example trackEvent for tracking playback of a movie.





    You can get the code here:
    https://github.com/purplecabbage/phonegap-plugins/tree/CoreDump/GoogleAnalytics

    More in depth info on Google Analytics for Mobile can be found here:
    Google SDK Docs
    http://code.google.com/mobile/analytics/docs/

    … and lots more info on how to use events so that you can track meaningful information on usage.
    http://code.google.com/apis/analytics/docs/tracking/eventTrackerGuide.html


    Next Steps


    Plugin work in general is ongoing. One thing in particular is that we want to make the JavaScript code that you include in your app exactly the same on all the different devices that use it. Currently it is sometimes necessary to have multiple JavaScript files, which is an unwanted evil.

    Another goal we are working towards is consistent plugin packaging. Instead of forcing developers to take different steps to ready their app to use a plugin on multiple devices, we want to use a plugin configuration file, so the app code will be exactly the same on each device.

    Integration between the PhoneGap Build service and custom Plugins is something we are working towards, so developers can just get down to writing their apps.

    Expect more plugins in the coming weeks, as we try to fill more ‘Gaps’ and make everyone’s PhoneGap apps easier to make.

    I welcome your comments, feedback, and questions.

  • Björn R

    following these instructions

    I got a build error. Something with
    “_sqlite3_prepare_v2 referenced …”

    FrameWork folder -> add -> existing Frameworks ->libsqlite3.0.dylib solved it.

  • Tom

    I’m having similar issues including “PhoneGapCommand.h No such file or directory” error.

    Any ideas? I’m using phonegap 1rc1

  • mrmacete

    PhoneGapCommand.h has just been renamed to PGPlugin.h

    should be sufficient to update the references in GoogleAnalyticsPlugin.h

  • Tom

    After updating to use PGPlugin I get sqlite3 errors. I really could use this plugin. Please update!!!!!!!

  • http://mill-industries.com Eric Mill

    Tom – link in the library for sqlite3. You want to right click on the Frameworks folder in XCode, then select Existing Frameworks. libsqlite3.dynlib should be listed there. That fixed it for me.

  • http://www.ifeelpixel.com Frederic P.

    Hello Jesse,

    I am testing the Beta of PhoneGap Build and I don’t know if the online APK creator supports custom plugins.
    What are the capabilities of PhoneGap Build about custom libraries? Is it possible to add a custom plugin to the Build?

    If Yes, does your developers can modify the PhoneGap Build scripts such that they add the UHL library (made by Immersion) directly to the build? Please. For more information see:
    http://www2.immersion.com/developers/index.php?option=com_content&view=article&id=495&Itemid=812

    Thanks for your answer.

  • Alex

    Am I missing something? The plug in appears to no longer be on github

  • Martijn

    Uhm. Where did the plugin go? Unable to download it from github!

  • Benny
  • http://www.sterin.it sterin

    Add to plugins.xml on phongap 1.0 (or later)!

  • http://www.sterin.it sterin

    ….Add to plugins.xml plugin name=”GoogleAnalyticsTracker” value=”com.phonegap.plugins.analytics.GoogleAnalyticsTracker” on phonegap 1.0 (or later)!

  • RoboBobo

    The directions say generic things like ‘add all the files’ And whenever directions are written like that you get errors like “PhoneGapCommand.h No such file or directory”

    I’m writing a hybrid app because I’m basically writing the app in HTML5/Javascript.

    But I really need to know how to program in Objective-C – because there aren’t any complete instruction on installing this plugin, and even stating its been renamed to PGPlugin.h doesn’t help unless you know to change #import “PhoneGapCommand.h” to #import

    Do you see how that’s not an obvious difference?

    Anyway – after you get it to compile, it then simply doesn’t work.

    I’m not saying it doesn’t work for anyone, but who knows what the exact steps and things you were supposed to do, to get it to work. I don’t.

    I’m very good at following a complete example – just a thought, thanks for trying anyway.

  • RoboBobo

    my above post I tried to say #import PhoneGap/PGPlugin.h

    but with the PhoneGAp/PGPlugin.h encased with “greater than” and “less than”

    It probably deleted that part because it looked like HTML markup…lol

  • clonyx

    Hi, you mention that the traditional html script tag will work on iOS if the device is connected to the internet. However I have also read in another posts that google analytics doesn’t work if the request is not made from a web server but a file system file. How did you implemented such approach?. I can’t use any plugins since I only have access to www folder (files inside the UIWebView)

    I know that this question is out of the scope of your plugin but as you mentioned that solution I really apretiate if you can give some light here.

    thank you,

  • Eyal

    In the new version of xcode, FrameWork folder -> add -> existing Frameworks doesn’t exist.
    The solution to the _sqlite3 errors is to go to the project page, choose the target, click on the “Build Phases” tab and in the “Link Binary with Libraries” press the + button in the bottom. then add libsqlite3.0.dylib & CFNetwork.framework

  • Allen

    Took a good 30 mins to get this working, have to get my google acc setup and ready, but so far it compiling,

    As the comments above say, the phonegapcommand is renamed to PGPlugin, so change that in the googleanalyticsplugin.h, and also change the @interface to : PGPlugin.

    For the people getting the ” “_OBJC_CLASS_$_GANTracker”, referenced from: ” error, you’ve got add the files/folders in ‘Crete groups for any added folders’, and it doesn’t hurt to tick the “copy items into destimation groups folder” option.

    You will have to add the other frameworks like the comment above (libsqlite3.0.dylib & CFNetwork.framework), and if you want to make things neater and organized just drag them into the appropriate folder within your project. If you get the red text in the ‘link binary with libraries’ pane just delete it from pane and drag back and it should work.

  • rajasa

    Seems to not work on phonegap 1.5. Tried to change the names to the cordova naming but got errors on built: 

    undefined symbol for architecture armv7 ”_sqlite3_reset”, referenced from. Anybody experience this?

  • http://www.webworks.dk/ Mark

    If anyone is looking to use Analytics in their PhoneGap app without this plugin (using the regular javascript API), I just want to point out that you cannot (easily) do that, even though the description here says that you can. PhoneGap loads the app’s main page using a file:// URL, which will prevent Analytics from setting the cookies that it needs to track traffic. I got it working using an embedded HTTP server acting as a proxy, but that opens up other issues, so in the end I am back to using the plugin.

  • Fábio Alencar

    Hello,
    I follow the steps on this link: 
    https://github.com/purplecabbage/phonegap-plugins/tree/master/Android/Analytics

    The plugin starts (i get the callback ”Start: success”) but it can’t track the page.
    the callback for window.plugins.analytics.trackPageView is always ”Track: failure”.What should i put if i want to track my main page(it’s just a test)? “index.html”?

    Thx!

  • Hooch

    How do Apple/Google feel about this?
    Normally when an app tacks things there’s a popup which asks if the user agrees to sending anonymous usage statistics.
    Does this plugin ask that?
    Will it get rejected from stores if it does this without permission?

  • Adrian Urso

    Good question I wondering too.

  • Lorena

    Hey there – Do you guys have a plug-in or some sort of documentation on how to tag/integrate a phonegap app with Omniture?  We are launching a phonegap app with our client and our client exclusively uses Omniture.  I have searched everywhere on the net to no luck.  Any suggestions?

  • Jesse

    Omniture is not currently supported, although the same methodology could be applied to wrapping their SDK calls to make them callable from JavaScript.  You can most likely expect a plugin to be written for this, either by Omniture or Adobe, but there is no current plan or word of when it will happen.

  • Jesse

    Google of course loves it, and Apple afaik has no opinion.
    Apple is taking steps to remove the unique device id from the API, so this may affect the use of the google analytics SDK in the future, although it is still permissible to use the UUID, it is officially deprecated.
    The plugin does not ask for permission, if you feel that you are violating your users’ privacy, then you should ask them yourself in your code.  The plugin plays by the rules, and does not itself access anything that would be a privacy concern.  What you log is up to you, but this is no different than any other native app.
    There is no way of knowing what will or will not be rejected.