I wrote this a couple months back for FFDMag and now that some time has passed I thought it would be a good idea to also post it on my blog and get some Google juice for the work that I put into it. So here it is:

In this time of economic crisis, marketing budgets are shifting from traditional to digital because of the later’s ability to provide data about its effects. Flash has never been great at web analytics, but a new library, Google Analytics for Flash, is going to change this. This article will focus on how to install this library, how to use it and will explain some of its key concepts.

Installation

Well the first thing to do before getting started is to install the library. This might not be as obvious as it should be so I thought it would be good to explain it here. When you download the zip file from the Google Code page for Google Analytics for Flash, what you’ll get in it is two SWC files. Now SWC files are a common thing in the Flex world, but they are not so common in the Flash world. This is where the difficulty lies.

Flash CS4

There is a new feature in Flash CS4 that enables you to import SWC libraries a bit in the way that you would do it in Flex. All you have to do is open the publish profile and click on the Flash tab. Now click on the Actionscript 3 settings; on the window that will pop-up you will see a red envelope icon, clicking on this will enable you to import the SWC file.

Flash CS3

Now it ain’t that easy for Flash developers still using Flash CS3 (the majority of them I guess). I have found two ways of getting the same results.

First you could use a Subversion client like TurtleSVN to checkout(download) the source code of the library. This will give you access to the Actionscript files (.as) that were used to make the SWC library. Once you have those files just copy them in your project directory and you’re ready to go.

If you don’t want to bother with svn, you can copy the SWC files in the Component directory of your Flash installation. Now this is the intended use of the SWC files by the makers, but I found it is more complicated than it should have been. If you want to do it that way copy the SWC files in the following folder in windows:

C:\Program Files\Adobe\Adobe Flash CS3\language\Configuration\Components

And the following folder if you are using a Mac:

Macintosh HD:Applications:Adobe Flash CS3:Configuration:Components

The next time you will start Flash, in your component window, you should see the Google Analytics for Flash components. Drag the component in the library and you can go on to the next step.

On to tracking

Tracking is the easiest part of the process and is fairly intuitive. You have to do a bit more work than you would with an HTML website, but in the end you gain more control.

All you have to do is import the library and create the tracker this way:

import com.google.analytics.AnalyticsTracker;
import com.google.analytics.GATracker;
 
var _tracker:AnalyticsTracker = new GATracker( main, "UA-7777777-7", "AS3");

The first parameter in this case refers to a DisplayObject on the stage or the stage itself. The second parameter is the id for the Google Analytics profile you want the data to be sent to. The third parameter is the mode in which the tracker will function, in this case AS3 mode. An other mode that the tracker can be set to is the Bridge mode; I’ll discuss the difference between the two modes later on.

You are now ready to track. The tracker you just created will give you access to two method of tracking: tracking pages and tracking events.

For pages, you can clearly grasp the concept when you think of an HTML website. Each time the browser will refresh or change a page and that page is from your website, a pageview is sent to Google Analytics. Now you can translate the same concept to Flash and rich internet applications, but those tends to have less pages than HTML websites. When I try to define pages in my Flash website, I try to think in sections, example: the contact section, the home section, the help section etc.

Here is the code you would write to track a pageview:

_tracker.trackPageview(yourSectionName + "/");

Events are a metric that is more suited to Flash and RIA than pageViews. Event tracking is still in beta so it is not enabled on all profiles. You can ask Google to activate events on your account by filling the form found on this page:

http://code.google.com/p/gaforflash/wiki/EventTrackingRequest.

Events are best suited to track user’s interaction with your project: how many user fully saw your video, how many clicked on the mute sound button, etc.

This is what you would write to send and event:

_tracker.trackEvent("English", "Client Satisfaction", "Question 3", value);

The trackEvent funciton can take up to 4 parameters, the last two being optional. They are in order Category, Action, Label and Value and are all Strings except the last one that has to be a non-negative integer. Google Analytics suggest some use of these parameters, but in the end, it’s up to you to decide how you want to define them. More information about Events here:

http://code.google.com/apis/analytics/docs/eventTrackerGuide.html

Bridge vs AS3

I have only talked about the AS3 mode so far because it is the one I use more often. It is mostly used when you’re entire site is made in Flash or also when your content will be embedded somewhere you don’t have access to the HTML. This is the case for widget and games that are embedded on multiple sites.

As for Bridge mode there is two cases where I would use it. First if your Flash is just a part of a bigger website done in HTML that already uses Google Analytics, then using Bridge mode will use the tracker of the html page blending in the data of the Flash content with the rest. Secondly, not all of the Google Analytics API is available using AS3 mode so if you need advanced functions or ones that are not enabled than you have no choices but to use Bridge mode. The code is a bit different from AS3 mode so I’m going to provide a sample:

var _tracker:AnalyticsTracker = new GATracker( main, "window.PageTracker", "Bridge");

The first parameter in this case still refers to a DisplayObject on the stage. The second one has to be the name of your Javascript PageTracker Object preceded by “window.” and the last one is to tell the tracker to be in Bridge mode. Since, Flash will need to communicate with the javascript while in Bridge mode, you have to be sure that allowScriptAccess is set to always in the html page that embeds the Flash content.

Visual Debug

One cool thing about GA for Flash is the Visual Debug. All you have to do to enable it is add an extra parameter when you initialize the tracker.

var _tracker:AnalyticsTracker = new GATracker( main, "UA-7777777-7", "AS3", true);

Doing this will add a layer on top of your application where all the actions the tracker performs will be listed.

What is neat about this is that you can now see instantly what you are tracking. With the javascript API, it is hard to see exactly what you are sending because you have to note down what you did and go check 4-5 hours later to see if tracked correctly (Google Analytics shows data after a delay of a few hours). With the Visual Debug you can see if you are sending more events than you should or if one label is misspelled etc.

Even if Google Analytics for Flash is a great library, it has some drawbacks, the biggest one being that it will add 40k to the size of your Flash content. But even with that in mind, I think it is worth using in every Flash project. Go on, get tracking!

Ressources

Google Code:

http://code.google.com/p/gaforflash/

Developer group:

http://groups.google.com/group/ga-for-flash?pli=1

Adobe Max presentation on Google Analytics for Flash:

http://tv.adobe.com/#vi+f15385v1040