Analytics SWF: Google Analytics Flash Tracking for Developers

This topic describes how to develop an analytics SWF for Google Analytics Flash Tracking.

The Video Cloud flexible player architecture enables you to incorporate your own custom SWF components into the player. With Google's Flash Tracking feature, you can track your players anywhere they are published without relying on in-page JavaScript code. Read Google Analytics Tracking for Adobe Flash to learn more about this feature.

If you are not familiar with ActionScript, consider using the Video Cloud out-of-the-box Google Analytics integration. You can find instructions on how to configure events for Google easily in the document, Integration with Google Analytics.

There is also a Google Analytics SWF available here in Open Source @ Brightcove which can be used out-of-the-box for simple analytics or you can customize it for your own data collection requirements.

Before you begin, read the introductory topic, Developing an Analytics SWF. In addition, read Using the Flash-only Player API SWC, Creating Custom Player Components, and Player ActionScript Wrapper Classes.

This topic will teach you how about:

1. Setting up your Google Analytics account.
2. Developing a Google Analytics Flash Tracking SWF component in ActionScript 3.
3. Adding the Google Analytics SWF to your Video Cloud players.
4. Viewing Video Cloud data in Google Analytics.

Setting up your Google Analytics account

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 because you can create multiple profiles for the same website (or player) so that you can filter and slice your data in various ways. In this topic, we'll create one profile to start with.

Using an existing Google Analytics account

If you already have a Profile in Google Analytics created for your web site to track page views, we highly recommend that you create a new Profile for the same web site that you will use for tracking Video Cloud data only. If you don't, you may overwrite other web site data that you're trying to track. You can read more about profiles in the Google Analytic Help documentation.

To create a profile, follow these steps:

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 time zone settings for the profile, if you like, and save.

Once you have created your profile, Google Analytics displays some tracking code and your alphanumeric Google account ID, which will look something like: AA-123456-A.

Note: You will not need the JavaScript tracking code to take advantage of the new Google Analytic Flash Tracking capabilities. However, you will need your Google Account ID. Save your Google Account ID somewhere; you'll need it later when you build the analytics SWF.

Developing a Google Analytics Flash Tracking SWF component in ActionScript 3

You can download the this component's source as a zip file. This sample file sends the player load, media begin, and stream complete events to Google Analytics to be tracked. You can extend the component to fire more events pretty easily.

Use the following steps to create a Google Analytics SWF component:

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 in the code source zip file noted at the beginning of this section. Note that this example requires that you use Flash CS4 or later.
2. Follow the instructions from Google to install the required component files. In this example, you are using the AnalyticsLibrary component and method, which you can read more about in the Google documentation.
3. The opening lines of the code start your package, import required libraries, declare your class, and declare some basic variables that you will use to hold Video Cloud player data.
4. You must define a constant that will be populated with your Google Account ID at runtime, as follows:

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

   The component will read your Google Account ID at runtime from the URL parameter gid. You will set up the URL with your Google ID later in this doc in the publishing module. In this example, use the ActionScript 3 Bridge mode and set debug to false. If you wish to learn more about these options, read about Tracking Modes in the Google documentation.
5. In the setInterface function, import the Video Cloud Flash-only 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. 

Tracking events vs. pages

Google provides two different APIs for tracking items on your website.  The first API tracks page views and the second API tracks specific events. The event tracking API was designed specifically to track interactions with Flash content. In other words, think of events like video play, video pause, and other events that occur as a viewer interacts with a Video Cloud player.  

An event has three different levels of data associated with it:

• Category. A name that you specify as a way to group objects that you want to track.
• Action. Typically, you will specify the action parameter that names the type of event or interaction that a viewer will have with a Video Cloud player or video.  
• Label. Labels provide an opportunity to specify additional information about a particular action.  For example, if there is a "pause" action in a a video, a label provides the ability to specify the timecode for the video when the action caused it to pause.

You can read more about events in the Google Analytics documentation.

Event tracking in Video Cloud sample code

The Video Cloud code in our example will track the following events:

• Video start. Fired anytime that a video is started.
• Video completed. Fired when the video playback is completed.
• Video progress. Fired at quartile percentages of playback (including 100% completion).
• Player load. Fired when the player loads before any video playback starts.

Here is the list of events that are fired and their associated category, action, and label:

Event Name	Category	Action	Label
Video start	video_start	video name	video timecode
Video completed	video_complete	video name	100
Video progress	video_progress	video name	percent complete (.25, .5, .75, 1)
Player load	player_load	URL that is embedding the player	Referrer URL that referenced the page that embeds the player

The fireEvent function: Firing player events to Google

Let's look at how you can track events in Google Analytics using the fireEvent function. Before we send the event to Google Analytics, we need to collect information about the player, playlist, and video currently loaded or playing:

private function fireEvent(eventName:String,loc:Number):void {
    var experienceId:Number  = _bcExperience.getExperienceID();
    var playerName:String  = _bcExperience.getPlayerName();
    var action:String = "";
    switch (eventName) {
    case EVENT_PLAYER_LOAD:
        var experienceURL:String = _bcExperience.getExperienceURL();
        var referrerURL:String = _bcExperience.getReferrerURL();
         _tracker.trackEvent(eventName,experienceURL,referrerURL);
         break;
         // add additional cases here if needed
    default:
         var video:Object = _bcVideo.getCurrentVideo();
         var playlistId:Number  = video.lineupId;
         var videoId:Number   = video.id;
         var videoName:String = video.displayName;
          _tracker.trackEvent(eventName,videoName,loc.toString());
    }

}

In this example, we chose to send different information for player loads than for other video type events. For player loads, we sent the URL where the player loaded, as well as the referring URL. For other events, we did not send the URL, but sent more in-depth information about the content that is playing back when the event occurs. When the trackEvent() method is called, the component sends the event to Google Analytics for tracking. The tracker essentially creates or increments the count in your Google Analytics account.

The registerEvents function: Add event listeners

The following code snippet creates a new Google Analytics tracking object named tracker. The code passes in the reference to the player stage, our Google Account ID (a constant, defined earlier), and the bridge mode and debug mode settings (which are also constants, defined earlier).

Then, it adds event listeners for template load events:

private function registerEvents():void {
   _bcStage = _bcExperience.getStage();
 
   // Create a Google tracker with reference to the Video Cloud 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 Video Cloud 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);
}

The initialize function: get reference to player modules

The initialize function retrieves references to modules in the player, in this case, experience and Stage.

The first thing to check is whether the ExperienceModule is available in the player. 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(), which listens for when MODULES_LOADED gets dispatched, regardless of the player settings in the Video Cloud Studio Publishing module. This code also checks 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();
    }
}

Adding the Google Analytics SWF to your Video Cloud players

Once you've created and compiled your Google Analytics tracking SWF component, 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, consult your webmaster. For more information and sample crossdomain files, read the topic, Cross-Domain Security.
3. Set your players to use the Google Analytics SWF. You can do this 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. For instance, to set your Analytics SWF URL, include the gid URL parameter:
   http://mysite.com/analytics.swf?gid=AA-123456-A
4. [Optional] Enable ActionScript/JavaScript APIs for your players that use the Analytics SWF. You can do this 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 Video Cloud data in Google Analytics

Once your player have been set up to fire data to Google Analytics 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 select Event Tracking from the submenu.
3. Notice that the Top Events are displayed on the front page.
4. Notice that the Video Names are displayed under the Event Action section.

Figure 1. Here is an example showing what your Google Analytics Event Tracking page might look like.

Notes and Limitations

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

1. 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.
2. Google Analytics has a page view limit. Google Analytics is a free service that offers users up to 5 million page views a month. If your site generates more than 5 million page views per month, you will need to link it to an active AdWords account 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).
3. 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.