Analytics SWF: Google Analytics Flash Tracking for Developers

If you are not familiar with ActionScript, please consider using our out of the box Google Analytics integration. You can find instructions on how to configure events for Google in this article: Easy Google Analytics Integration for Publishers.

This topic describes how to develop an analytics SWF, using as an example an analytics SWF for Google Analytics Flash Tracking. Before you begin, read the introductory topic, Developing an Analytics SWF, Using the Player API SWC, Creating Custom Player Components, and Player ActionScript Wrapper Classes.

This topic shows you how to integrate Brightcove with Google Analytics Flash Tracking. With Google's Flash Tracking feature, you can track your players anywhere they are published without relying on in-page JavaScript code. This Google documentation introduces Google's Flash Tracking.

Getting started with Google Analytics

The first step in your Google Analytics integration is to open a Google Analytics account. This is free.

Once you have created and signed into your Google Analytics account, create a website profile. The website profile is Google's name for a view into your reports. It can be pretty powerful as you can create multiple profiles for the same website (or player) in order to filter and slice your data in various ways. We'll just create one profile to start with.

Even if you already have a Profile in Google Analytics created for your website to track page views, we highly recommend you create a new Profile for the same website that will be used for tracking Brightcove data only. You can read more about profiles in Google Analytic's Help documentation.

To create a profile:

1. Click the "Add Website Profile" link.
2. In the "Add a Profile for a new domain" field, enter the URL to your player, not including the actual HTML file name.
3. Edit the timezone settings for the profile, if you like, and save.

Once your profile is created, Google Analytics presents some tracking code and your alphanumeric Google account ID, which looks something like this: "AA-123456-A".

You won't need the JavaScript tracking code to take advantage of Google Analytic's new Flash Tracking capabilities. However, you will need your Google Account ID. Save this ID somewhere; you'll need it later while building the Analytics SWF.

Building a Google Analytics Flash Tracking SWF for ActionScript 3

Examine the source for the example Google Analytics SWF. You can also download it as a zip file. This sample file fires the player load, stream start, and stream complete events to Google Analytics. You can extend it to fire more events pretty easily.

Here are the main steps in creating a Google Analytics SWF:

1. Create an ActionScript 3 .as file and link it to a .fla shell file. The .fla doesn't actually contain anything except the .as file. You can download an example .fla file.
2. Follow the instructions from Google here to install the required component files. In our example, we are using the AnalyticsLibrary component and method (http://code.google.com/apis/analytics/docs/flashTrackingSetupFlash.html#useAnalyticsLibrary).
3. In the opening lines of the code, you start your package, then import some libraries you're going to need, declare your class, and declare some basic variables that you will use to hold Brightcove player data.
4. At this point, we define a constant that will be populated with your Google Account ID at runtime:

   // Constants
   var ACCOUNT_ID : String = loaderInfo.parameters.gid;
   var BRIDGE_MODE : String = "AS3";
   var DEBUG_MODE : Boolean = false;

   Your Google Account ID will be read in at runtime from the URL parameter 'gid'. We'll set up the URL with your Google ID later in this doc in the publishing module. In this example, we will use the AS3 Bridge mode and set debug to false. If you wish to learn more about these options, please read http://code.google.com/apis/analytics/docs/flashTrackingIntro.html#trackingModes
5. In the setInterface function, import the Brightcove Player API modules you need, and add event listeners for template load and content load events
6. In the onTemplateReady event handler, add event listeners for player events.
7. In the fireEvent function, collect the event information and send it to Google Analytics.

fireEvent function: firing player events to Google

Google tracks player events as 'virtual URLs', ie a player event is like a page view. Let's look at how we can track events in Google using the fireEvent function. Before we send the event to Google we need to collect information about the player, playlist, and video currently loaded or playing:

private function fireEvent(eventName:String):void {
            var experienceId:Number  = _bcExperience.getExperienceID();
            var action:String = "";
 
            switch (eventName) {
                case EVENT_PLAYER_LOAD:
                    var experienceURL:String = _bcExperience.getExperienceURL();
                    var referrerURL:String = _bcExperience.getReferrerURL();
                    action = "'playerid=" + experienceId + "/url=" + experienceURL
                     + "/refurl=" + referrerURL + "/" + eventName;
                    break;
                // add additional cases here if needed
                default:
                    var video:Object = _bcVideo.getCurrentVideo();
                    var playlistId:Number  = video.lineupId;
                    var videoId:Number   = video.id;
                    action = "'/playerid=" + experienceId + "/plid=" + playlistId
                     + "/vid=" + videoId + "/" + eventName;
            }
 
            _tracker.trackPageview(action);
        }

In this example, we have chosen to send different information for player loads than for other video type events. For player loads, we send the URL where the player loaded, as well as the referring URL. For other events, we ignore the URL, but send more in-depth information about the content that is playing back when the event occurs. The trackPageview() method is when the event is actually sent to Google for tracking. The tracker essentially creates or increments the pageview count for the virtual page corresponding to the player event that occurred.

registerEvents function: Add Event Listeners

A new Google Analytics tracking object, named tracker is created. We pass in the reference to the player stage, our Google Account ID (a constant, defined earlier), the bridge mode and debug mode settings (also constants, defined earlier).

Then, we add event listeners for template load events:

private function registerEvents():void {
            _bcStage = _bcExperience.getStage();
 
            // Create a Google tracker with reference to the Brightcove player stage and your Google Account ID
            _tracker = new GATracker(_bcStage, ACCOUNT_ID, BRIDGE_MODE, DEBUG_MODE);
 
            _bcVideo = player.getModule(APIModules.VIDEO_PLAYER) as VideoPlayerModule;
            if (_bcVideo != null) {
                _bcVideo.addEventListener(MediaEvent.BEGIN, onMediaBegin);
                _bcVideo.addEventListener(MediaEvent.COMPLETE, onMediaComplete);
                // NOTE: you may choose to add more Brightcove player event listeners here
            }
 
            // if you want to track BC menu events, get a reference to the Menu module here
            //_bcMenu = player.getModule(APIModules.MENU) as MenuModule;
 
            fireEvent(EVENT_PLAYER_LOAD);
        }

initialize function: get reference to player modules

In initialize, we retrieve references to modules in the player, in this experience and the Stage.

The first thing to check is whether the ExperienceModule in the player is available. If it is not, it means that the API was not enabled for the player instance and so the required API classes were not loaded. You can force the loading of these classes through a call to loadModules(), listening for when MODULES_LOADED gets dispatched, regardless of the player settings in the Publishing module. We also that check whether the stage is available on load. It is important to check that the stage is available before firing the initial player event to Google Analytics.

/*
 * The player is ready for interaction. Checks for access to stage.
 */
 override protected function initialize():void {
    _bcExperience = player.getModule(APIModules.EXPERIENCE) as ExperienceModule;
    _bcStage = _bcExperience.getStage();
    if (_bcStage == null) {
          _bcExperience.addEventListener(ExperienceEvent.ADDED_TO_STAGE, onAddedToStage);
    } else {
          registerEvents();
    }
}

Using the Google Analytics SWF

Once you've created and compiled your Google Analytics tracking SWF, you need to make it available in your players. To use the Google Analytics SWF, you need to:

1. Host the SWF at a URL where it is accessible to your players.
2. Make sure your crossdomain.xml file is set up to allow the Flash player to access data from the Brightcove and Google domains. To do this, add the following domains to your site's crossdomain.xml file:

   <allow-access-from domain="*.brightcove.com" />
   <allow-access-from domain="*.google-analytics.com" />

   You may have to contact your webmaster in order to make this modification. The crossdomain.xml file is a file that lives on your domain that contains a list of trusted third party domains. If you're unsure how to modify this file as described here, please consult your webmaster. For more information and sample crossdomain files, read Cross-Domain Security.
3. Set your players to use the Google Analytics SWF. You can do this either by editing your player settings in the Publishing module or by adding the SWF as a module in your player template, as described in Developing an Analytics SWF. Note that you will need to pass in your Google ID using the 'gid' parameter in the Analytics SWF URL you enter. So, for example, you should set your Analytics SWF URL as:
   http://mysite.com/analytics.swf?gid=AA-123456-A
4. [Optional] Enable ActionScript/JavaScript APIs for your players that use the Analytics SWF in the Edit Settings dialog of the Publishing module. If you choose not to enable APIs for your players, the sample integration code will still work since we added the API enablement directly into the actionscript code.

Once your player has been published with the Google tracking code, it can take up to 24 hours for your events to appear in Google reports.

Viewing Brightcove Data in Google Analytics

Once your player have been set up to fire data to Google as outlined in the steps above, you can view your video data in Google Analytics reports. To do so:

1. Sign in to your Google Analytics account.
2. In the left sidebar menu, click to view your Content report and then select 'Top Content' from the submenu.
3. Select the appropriate time period for your report and observe that the Brightcove events are tracked as 'virtual' page views in the displayed report.
4. If you want to search the reports for a specific Brightcove Video or Player, use the 'Find Page' search box at the bottom of the page or download the entire report in the format of your choice to search/filter the data.

Notes and Limitations

Note the following limitations and other information about using Google Analytics:

• You can set the path to the Web Analytics SWF in each player, or in a custom player template, but you cannot set it at the account level for all of your players.
• Google Analytics has a pageview limit. Google Analytics is a free service that offers users up to 5 million pageviews a month. If your site generates more than 5 million pageviews per month, you will need to link it to an active AdWords account in order to avoid interruption of your Google Analytics service. Google Analytics currently defines an active AdWords account as an AdWords account that has at least one active and running Campaign, with a minimum budget of $1 per day (or the equivalent amount in a non-U.S. currency).
• Google recommends against disabling persistent tracking cookies set by Google Analytics. If you do so, you will lose data in several reports including but not limited to, New Vs. Returning, Visitor Loyalty, and everything under Traffic Sources. If you need to disable all cookies on your site, follow the instructions on the Google Analytics website for information about how to do so.