8 November 2010
Some familiarity with SiteCatalyst or analytics implementations is helpful, but not required. Even if you are new to tracking analytics, this article provides new strategies to implement tracking of Flash content.
To follow along with these instructions, you'll need a SiteCatalyst account. If you do not have one, please visit the SiteCatalyst product overview page to request more information. Learn more about getting a SiteCatalyst account.
Download the SiteCatalyst extension for Flash Professional CS5 for free.
In this tutorial, you'll learn how to add SiteCatalyst tracking to a SWF file using the features provided by the Adobe SiteCatalyst extension for Adobe Flash Professional CS5. SiteCatalyst is one of the most powerful web analytics tools on the market. It offers the ability to track visitor behavior and gather various data in meaningful reports, organized in report suites. Among these reports, statistics such as client conversion funnels, user activity, and product sales are broken down by events, such as shopping cart additions or checkouts, movie viewing statistics, and many more.
A significant number of ActionScript variables are required to reach this level of tracking granularity. In some cases, hundreds of variables are used for a single call, corresponding to user events, such as the click of a button during checkout.
The Adobe SiteCatalyst extension for Flash Professional CS5 facilitates collaboration of an entire web development team, including marketers, designers, and developers to implement analytics directly in the authoring environment where the site is produced. The wizard in the extension guides you through the process of mapping the dozens of available SiteCatalyst variables to more meaningful names. The fast and error-free implementation makes it easy to begin using the tracking library right away.
When you're creating a presentation site, online store, job portal, media center, or simply a banner ad, it's critical to understand your visitors' preferences so you can deliver the best possible content to them. Whether your visitors are viewing certain pages, following specific click-through patterns, or performing actions—such as playing a video, adding a product to the shopping cart or simply leaving your site—the custom information you track with your SiteCatalyst account can be agregated later into rich reports.
For the purposes of this sample project, you'll add tracking to a sample Flash ad provided in the sample files folder.
To get started, you need to install the SiteCatalyst extension for Flash Professional CS5 and make some basic configurations to your SiteCatalyst account:
Note: If you are using Windows Vista or Windows 7, you need to open Extension Manager as Administrator before opening the installer file. To do this, simply right-click an Extension Manager shortcut or executable and select the option to Run as Administrator.
As you follow along with these instructions, you'll make several calls to your SiteCatalyst account. To avoid potentially adding data to any existing report suites you might have, you'll begin by creating a new report suite for the purposes of testing.
Note: If you do not currently have an account with administrator privileges and you cannot add new report suites, please contact your company's account administrator and ask them to perform the remainder of this sub-section for you.
This operation creates a basic report suite with an ID like this:
In the name above,
[companyID] is replaced with the client code set for your account. Next, you'll verify that you have access to the newly created report suite:
After completing these steps, you've created a user group named SCDemo.
Note: Only ActionScript 3 files are supported by the SiteCatalyst extension at this time.
A tracking library is a reusable component that enables you to predefine several settings for the tracking calls. You can then export them to a Flash component (SWC file) and share them with your team members. This is a great way to ensure consistency of tracking across multiple assets which are part of the same project. The tracking call settings include the following:
eVar5). Since SiteCatalyst provides a fully customizable mechanism of sending information to the servers, it means that the names are very general by default. A web analyst or Flash developer can associate these generic variables with information specific to a website or creative presentation, such as a store section or promotion.
pageNameneeds to be entered for every tracking call.
The tracking library includes ActionScript classes for a service, which defines the common settings for all calls that use the library, and a tracker, which describes individual calls. It also contains a class for each event and each merchandising variable. More detailed information about configuring trackers are covered in the next section of this article.
In order to create a new tracking library, you'll use the Library Creation Wizard:
pageNameand click Next.
Note: You can easily add and remove entries in the variable list. By default, all enabled eVars and props are included in the list. However, you can add any of the standard variables (such as pageName, campaign, zip, etc.), as well as remove unused eVars, properties, or events.
prop2) variable (see Figure 6).
eVar1) variable required by clicking the check box next to it. Click Next.
After completing the steps listed above, several files are generated. They are organized in a directory structure under the folder where the JJEsquire-promo.fla file resides (in the sample files folder). This directory structure includes the package name provided in the final screen of the wizard. (For example, if the package name is
com.adobe.reportsuite, the corresponding folder will be com/adobe/reportsuite).
An ActionScript file (acrjjesquirescLibrary.as) and a couple of other support files are generated in the same folder as the project JJEsquire-promo.fla file. The acrjjesquirescLibrary.as file describes the tracking library. The files inside the package describe a service class, a tracker class and a class for each event and each merchandising variable.
When you configure your own analytics, you can choose to use the Basic setup of the Wizard, which outputs the same files—it guides you through the same configuration process with less options.
In the SiteCatalyst panel, notice that an entry has appeared in the Libraries tab (called
[companyId]jjesquirescService), and that the Trackers tab is now active. At this point, you've created the tracking library, which is the general framework you will use to implement analytics for your current project. You can easily share this library with other team members by clicking the Export button next to it. This operation will package everything in a single .swc component that other team members can import in Flash Professional CS5, using the SiteCatalyst extension.
In the next section, you'll learn how to add a tracker to the Details button, using the tracking library you just created.
A tracker can be added for each user action on a Flash interactive object. To illustrate how this works, you'll add a tracker to trigger a call when the user clicks the Details button of the sample project banner ad.
Each tracker must be connected to a tracking library, so before adding a tracker you'll need to create or import one. To accomplish this, you'll follow the steps outlined in the section called Creating a SiteCatalyst tracking library in the previous section of this article.
Note: Complex websites may use more than one tracking library. The SiteCatalyst extension does not place a restriction on the number of tracking libraries used in a website, as long as each tracker is connected to one library.
A tracking library contains general data, common for most of the calls fired by your Flash content. A tracker extends the functionality of a tracking library, by using all its settings and describing the particular aspects of the call that is triggered by a user action, such as inputting text or hovering over a button. There are no limitations to the activities you can track; you can set a tracker for any combination of Flash objects on the Stage (including movie clips, buttons, input text fields, dynamic text fields) and a Flash event (such as click, mouseOver, keyUp and many others).
Follow these steps to add a new tracker:
Note: Only symbols that accept instance names are supported (such as movie clips, buttons, dynamic text fields, or input text fields). Nested symbols are also supported (in the case of a movie clip inside a movie clip), except for symbols placed inside of a button, because button timelines do not support ActionScript code.
A tracker has been added in the upper grid. Trackers selected in the upper grid can be configured in the lower grid. The new tracker has a default name, a default triggering Flash event (click) and is set to the corresponding tracking library. Later, you can use this screen to change any of these settings as desired, but remember that a value is required for each of the fields (see Figure 8). The Events and Products lists will be covered in another article.
Additionally, you can configure any number of SiteCatalyst variables, which were previously included in the library. Any variables set as required will display an asterisk next to them, to indicate they must have a value (such as
InternalPromotion). Unless you provide values for all of the required variables, you cannot save the tracker.
So, you'll need to input a value for the required variable. For this one, we want to describe which section of the ad was showing when the user clicks the button. Notice that on the actions layer of the sample FLA file, a variable is defined:
var tag = "Shop Now";
(Press F9 (Windows) or Option-F9 (Mac) to open the Actions panel and review the ActionScript code.)
The value of the variable changes for each section of the ad. You can see this change by reviewing the contents on frames 1, 177, and 467 of the Timeline. To use this variable to provide a value to a SiteCatalyst variable, you'll use its dynamic values, like this:
InternalPromotionvariable. This will activate dynamic values for that variable.
Note: Dynamic values can be activated in the same way for most of the variables set on services and trackers, whether they are required or not.
In the Timeline, notice that a new layer named SC Tracking Layer has been created. This layer contains the generated code that handles the reporting of data to SiteCatalyst (see Figure 10).
Note: To see the generated ActionScript code, select Frame 1 of the SC Tracking Layer and open the Actions panel (press F9 on Windows or Option-F9 on Mac OS X).
In this code, you'll see two instances (one for service and one for tracker) and the additional settings applied to them, according to the changes you made in the SiteCatalyst panel. The code for the service instance is always generated on the first keyframe of the main Timeline, and the code for the tracker instance is always generated on the keyframe and timeline corresponding to the target object. In this example, they are both on the same keyframe.
However, notice that in this case, the tracker code executes only on the first frame. The tag variable changes three times while running the SWF file, on frames 1, 177, and 467. In order for the tracker to send updated data at runtime, make the following adjustments:
detailsBtn_tracker1.InternalPromotion = tag;
After making these changes, the tracker can send information to the SiteCatalyst server regarding the context in which the button was clicked, to track which section of the movie was playing when the visitor clicked the Details button.
In the next section, you'll learn how to test and debug your analytics implementation.
Debugging SiteCatalyst instrumentation in Flash Professional is very straightforward. Follow these steps to see the calls, as they fire at runtime, appear in the Output panel:
Note: debugTracking is a configuration variable. Several such variables are automatically available to the tracking library, even though you didn't map them in the wizard. These default variables set up the way calls are fired when the visitor triggers them. For example, you can use delayTracking to insert a delay in triggering the call, or trackLocal to prohibit data from reaching the report suites. For a complete list of configuration variables, refer to the SiteCatalyst implementation manual (PDF, 1.6 MB).
Note: During the generation process, the entire contents of the SC Tracking Layer are regenerated. For this reason, it is strongly recommended that you do not attempt to customize the code. Doing so may result in losing the changes you made in the panel.
As you click the Details button, the tracking information appears in the Output panel (see Figure 12). This information consists of the full URL of the call, followed by a list of variables passed along in this URL.
All of the variables you have set in the tracking library and on the tracker appear in this list (
c2). Additionally, a few more variables are populated automatically. For example,
s describes the visitor's screen resolution.
Notice that the value stored for
v1 is populated with a different value, depending on the section of the ad displayed when you clicked the Details button. Play the movie again, and try clicking the Details button three times: once while each of the three images is displayed. Notice the three calls shown in the Output panel display different values for
You can also debug SiteCatalyst tracking using package sniffers (such as Fiddler on Windows or Charles Proxy on Mac OS X) or directly in the browser (using several Firefox add-ons, such as Firebug, HttpFox, and others). FireBug has an extension called OmniBug, which displays SiteCatalyst calls in an easy-to-read format.
As you've followed along with this article, you've learned about two new concepts for implementing SiteCatalyst tracking in Flash Professional: tracking libraries and trackers. These elements are designed to ease the process of implementation while maintaining a high level of flexibility for tracking your Flash projects.
A tracking library hides the complexity of SiteCatalyst implementations by helping you map proprietary variable names to more user-friendly names, using a Tracker class and a Service class. When setting up new libraries and trackers, you can add and remove variables and configure their values. The settings on the service are aggregated with the settings of a tracker in order to populate an AppMeasurement instance. A tracker-level value overrides a library-level value if a variable is set on both. However, given the general versus particular nature of libraries and trackers, there are some differences in terms of what variables are available for each of them.
When setting up a library, you can configure mapped eVars and props, standard tracking variables (such as pageName and campaign), configuration variables (including debugTracking) and you can add any number of production and development report suites. The configuration variables and the report suites are considered to be common for most calls which use the same tracking library, so they can only be configured for the library. To update these settings, you'll make changes in the Libraries tab of the SiteCatalyst panel.
Any eVar, prop or basic variable set as required in the wizard is available only in the tracker. Use the Trackers tab to configure mapped eVars and props, standard tracking variables (such as pageName and campaign), products and events for each tracker. As mentioned previously, settings for the products and events attributes will be covered in an upcoming article.
This article describes how to implement a basic tracking workflow. You've learned how to create a tracking library and add a tracking call that gets triggered when a visitor clicks a button. To learn more about Adobe SiteCatalyst, check out these additional resources:
Adobe also offers a free SiteCatalyst extension for Flash Builder 4.0.1. See the article titled Introducing the SiteCatalyst Extension for Flash Builder 4 to learn more.