Google Analytics Tracking for Adobe Flash

The Google Analytics Tracking for Adobe Flash component makes it easy for you to implement Google Analytics in your Flash-driven content. This component, developed by Adobe Systems, Inc., contains all of the functionality of the Google Analytics Javascript code. The Flash Tracking component is a compiled tracking object native to ActionScript 3, making Analytics implementation intuitive in Flash, and Flex development environments.

Why Use Flash Tracking?

Without the Google Analytics Tracking for Adobe Flash component, tracking Adobe Flash content with Google Analytics involves a number of technical hurdles. First, you must develop a custom interface to ga.js so that your Flash application can execute the appropriate Analytics method, such as trackPageview() or trackEvent(). In addition, you must also anticipate whether your Flash content will have access to the browser Document Object Model (DOM), since tracking fails for those objects where access to the DOM is denied (typically when your content resides on 3rd party sites). This involves understanding how to use the ExternalInterface call in ActionScript 3 to access the browser DOM and to degrade when access is denied.

The Google Analytics for Adobe Flash component simplifies tracking your Flash content and handles DOM access gracefully. It is useful for a number of common tracking purposes in Flash, such as: :

  • an embedded Flash widget on an HTML page
  • a standalone Flex application or Flash-only site hosted on an HTML page
  • a distributed Flex/Flash game or program where the developer has no control over where the widget will be placed

Keep in mind that tracking applications in Flash has some structural variations from tracking website pages. Familiarity with Analytics Tracking is essential to understanding how this plug-in works. You can also view the Design Documentation for this project for detailed information on how the Analytics Tracking model has been ported over for this component.

Note: Currently, Flash tracking is available for any Flash content embedded in a web page. Tracking of data sent from Adobe Air, Shockwave, or via the Flash IDE (e.g. using Test Movie) is not supported at this time.

Supported Development Environments

You can develop Analytics Tracking for Flash in either Adobe Flash or Adobe Flex environments. Each environment requires a different component, which you can download from http://code.google.com/p/gaforflash/. These components are based on ActionScript 3 and can be set up in one of two ways for each environment:

In Adobe Flash

  • Add and configure a simple component in the component inspector and drag it to the stage.
  • Import the Flash Tracking libraries directly into your library and start coding.

In Adobe Flex

  • Include an MXML component that you configure from am MXML file.
  • Import the Flash Tracking libraries into your script tags/AS3 files.

How Does the Component Work?

In order to use the Flash tracking component in your environment, you either use the visual tools inside Flash, or you set up the tracking object directly in your code. Regardless of whether you are setting up the component visually or via code, you provide the following elements:

  • the web property ID—This is also known as the UA number of your tracking code and looks like UA-xxxxx-yy, where the x's and y's are replaced with the numbers that correspond to your account and view (profile) information for the object you are tracking. See Web Property for more information.
  • the tracking mode—Choose either bridge mode or AS3 mode. This mode determines how your tracking communicates with the Analytics servers and is described in detail below.
  • the debugging mode—No matter which environment or tracking mode you use, you can turn debugging on to validate and test your tracking.

Tracking Modes

Depending upon on how you distribute your Flash content, the Analytics for Flash component communicates to the Analytics servers either by bridging the communication between the Flash content on an existing Analytics tracking installation, or by communicating directly to the Analytics servers. These two modes are called bridge mode and AS3 mode, respectively. Both modes use the same Analytics tracking functionality, and it's easy to switch your Flash application from one mode to the other. In addition to choosing a communication mode for Analytics tracking, you can also use a debug mode to troubleshoot or validate your tracking.

In either mode, allowscriptaccess must equal always in order for campaign tracking to work. This parameter turns on read access to the page's URL and referrer information required by the Flash tracking code. Without allowscriptaccess, the Analytics tracking code degrades gracefully. It still provides most user activity data, but will not confirm to the Google Analytics campaign attribution model.

Bridge Mode

Use this mode if you control both the HTML page and the Flash content. This mode is best if you have already implemented Google Analytics (ga.js) tracking on your website and you want to add tracking to embedded Flash content. The bridge mode simplifies Flash-to-JavaScript communication by providing a unified ActionScript 3 interface to the ga.js code. It provides the connection from the ActionScript 3 calls to the Analytics JavaScript in order to make the tracking work.

The connection to the Google Analytics Tracking Code can be configured through the web property ID parameter in one of two ways:

  • Most common method. The Google Analytics Tracking Code object already exists on your page with its own name, such as pageTracker. In this case, you provide the full DOM reference to the tracking object. For example, if your object is called pageTracker, you would reference that object in your code as window.pageTracker. For example, the following code snippet illustrates how this would be configured using the Adobe Flex environment with ActionScript 3:
    tracker = new GATracker( this, "window.pageTracker", "Bridge", false );

  • Alternate method. If you have not created a page tracking object on your page, you can simply pass in your web property ID, and a JavaScript tracking code object will be created for you. With this method, reference to the base ga.js javascript source file is still required on your HTML page. The following code snippet illustrates how this would be configured using the Adobe Flex environment with ActionScript 3:
    tracker = new GATracker( this, "UA-12345-22", "Bridge", false );

In order for bridge mode to function correctly, ExternalInterface.available must be set to true in your ActionScript 3 code. This also means that allowScriptAccess should be set to always in the HTML page that embeds the Flash content. The following example illustrates HTML code configured for bridge mode:

<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
     id="flex_component" width="800" height="600"
     codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab">
     <param name="movie" value="flex_component.swf" />
     <param name="quality" value="high" />
     <param name="bgcolor" value="#869ca7" />
     <param name="allowScriptAccess" value="always" />
     <embed src="flex_component.swf" quality="high" bgcolor="#869ca7"
         width="800" height="600" name="flex_component" align="middle"
         play="true"
         loop="false"
         quality="high"
         allowScriptAccess="always"
         type="application/x-shockwave-flash"
         pluginspage="http://www.adobe.com/go/getflashplayer">
      </embed>
</object>

 

AS3 Mode

Use this mode if you control the Adobe Flash ActionScript 3 code, but you do not control the hosting environment of your Adobe Flash application. For example, if you are developing Flash content for distribution across many sites, then you would use AS3 mode. AS3 mode is completely independent from the ga.js tracking code and contains all the Analytics tracking functionality. There is no need for a separate ga.js tracking installation with this mode. In addition, AS3 mode uses the Flash storage mechanism to track session information for the user.

For certain DOM parameters such as language, the AS3 component tries to retrieve the values from the browser. If the values are not present, the component either uses the Flash equivalent value or defaults to no.

Troubleshooting and Validation

The Google Analytics Tracking for Adobe Flash component provides a debug mode to simplify validation and troubleshooting. When enabled, all tracking data is intercepted and directed to a screen in a text box instead of the Analytics servers. In this mode, you can see real-time the data that otherwise would be collected by the server. This feature also helps keep test data outside of your production data. You can enable the troubleshooting feature can by setting the visualDebug option to true in the component inspector.

Examples

For detailed examples on implementing tracking in the different development environments, see the following:

Flash

Flex

Versioning

You can find the latest version of the tracking components as a ZIP file at http://code.google.com/p/gaforflash/downloads/list. Each download contains all tracking components along with related documentation. The file name for the download file will display the version number of the code it contains.

You can also use the following statements in your code to print the component's current version number into the output console.

import com.google.analytics.API;
trace(API.version);