Getting started with the Adobe SiteCatalyst extension for Flash Professional CS5

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.

Installing and opening the extension

To get started, you need to install the SiteCatalyst extension for Flash Professional CS5 and make some basic configurations to your SiteCatalyst account:

1. Download the installer file from the SiteCatalyst product page on the Adobe website.
2. Double-click the installer file to launch it. Click Accept in the Adobe Extension Manager window that appears.

   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.

3. After successfully installing the extension, close the Extension Manager window.
4. Open Flash Professional CS5.
5. Select Window > Extensions > Adobe SiteCatalyst. The SiteCatalyst panel appears with a message indicating that there is no document opened (see Figure 1).

6. Feel free to drag or dock the panel as desired to fit your Flash workspace.

Configuring the SiteCatalyst account for this tutorial

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.

1. Open a browser and login to http://sc.omniture.com with your SiteCatalyst account.
2. In the upper-right corner, click Admin > Report Suites.
3. Select Create New > Report Suite.
4. Use the menu to select Create from a template and choose the Support Media template.
5. In the Report Suite ID field, enter JJEsquireSC.
6. In the Site title field, enter JJEsquireSC.
7. Select your time zone using the Time Zone menu.
8. In the Estimated Page Views Per Day field, enter 100.
9. Click the Create Report Suite button.

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:

1. In the upper-right corner, choose Admin > User Management.
2. Choose the Edit Groups option.
3. On the right side of the window, click Add New User Group.
4. In the Group Name field, enter SCDemo.
5. In the Report Suite Access section, select the JJEsquireSC entry in the left table and click Add.
6. In the Assign User Logins section, select your username and click Add.
7. Click Save Group.

After completing these steps, you've created a user group named SCDemo.

Opening the extension

1. Unzip the sample files archive provided at the beginning of this article.
2. Open the JJEsquire-promo.fla file by double-clicking it in the sample files folder.

   Note: Only ActionScript 3 files are supported by the SiteCatalyst extension at this time.

3. If the SiteCatalyst panel is not already visible, you can see it by selecting Window > Extensions > Adobe SiteCatalyst. The panel displays the login state (see Figure 2).

4. Enter your SiteCatalyst account information and click Sign in to proceed to the next screen (see Figure 3).

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:

• User-friendly variable names: Most variables initially have generic names (such as prop13 or 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.
• Setting the default values: You can assign a default value for every variable. For example, you can specify the store section in the sample creative as Women's.
• Setting variables as required: You can set a reminder not to forget a certain variable when configuring a tracking call. For example, you can specify that pageName needs to be entered for every tracking call.
• Configure tracking: You can facilitate the reporting process by setting information such as which report suites will collect the data, SiteCatalyst tracking server address, website currency, and so on.

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:

1. In the Libraries tab of the SiteCatalyst panel, click Create library.
2. In the wizard window, select Advanced Setup and click Next.
3. Select the report suite you have created in the setup section described earlier. Either select the report suite name using the menu, or type its name in the field, and click Next (see Figure 4).

4. The wizard displays the Variable Mapping screen (see Figure 5). This allows you to associate SiteCatalyst variables to meaningful names. By default, they use the business names provided in the online SiteCatalyst administration. In the second item from the top, enter the new Class Property Name, Section, for prop2.

5. On this screen you may also add standard tracking variables to the mapping. Click the "+" button below the grid. Select pageName and 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.

6. On the Configure Variables screen, you can add default values and set variables as required. In the grid, enter Women's as a default value for the Section (prop2) variable (see Figure 6).

7. Make the InternalPromotion (eVar1) variable required by clicking the check box next to it. Click Next.
8. In the Select Success Events screen click Next. The settings on this screen will be covered in a future tutorial.
9. The last screen lets you configure some basic settings about your website (such as the currency used in the online store) and some tracking library settings (including the package name, which is the location where the files will be generated). For the purposes of this article, keep all the default settings. Click Generate.
10. In the panel, the Info window is displayed, stating that the Tracking Library files were successfully generated. Click OK to close the Info window.

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:

1. On the Stage, select the Details button. (This is the symbol that the visitor will click to trigger the tracking calls).

   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.

2. In the SiteCatalyst panel, click the Trackers tab.
3. Click Add tracker.
4. The Target Selection window appears. You can use the menu to select a symbol if more than one symbol is selected on the Stage. In this case, you've only selected the single Details button symbol, so the menu only displays one option. Click Continue (see Figure 7).

5. If the selected symbol does not have an instance name already, you will be prompted for one. Enter the instance name: detailsBtn and click Continue.

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:

(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:

1. Click the lightning bolt icon next to the InternalPromotion variable. 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.

2. Use as value the name of the existing ActionScript variable by entering the word tag in the right column of the InternalPromotion variable.
3. Add another variable by clicking the "+" button on the right side of the panel.
4. In the menu that appears, select Section.
5. Click on an empty row to set the variable. Now you can see that this variable was provided with a default value during library generation, and that value (Women's) appears next to the variable's name (see Figure 9).

6. When the tracker is complete, click Apply to save the changes. The SiteCatalyst panel will generate the necessary code automatically.

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:

1. Locate and copy (Control+C on Windows or Command+C on Mac OS X) the line of code on Frame 1 that assigns the InternalPromotion variable:

2. Select Frame 177 of the actions layer in the Timeline.
3. In the Actions panel, paste the line of code after the existing code (by pressing Control+V on Windows or Command+V on Mac OS X).
4. Next, select Frame 467 of the actions layer.
5. In the Actions panel, paste the line of code after the existing code (Control+V on Windows or Command+V on Mac OS X). Save the FLA file.

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:

1. Select the Libraries tab in the SiteCatalyst panel.
2. Click the "+" button on the top-right corner to add a variable on the selected service.
3. Use the menu to select: debugTracking.

   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).

4. Use the menu in the right column to select true as the value for the variable you just added (see Figure 11).

5. Click Apply to save your changes and update the generated code.

   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.

6. Play the movie (press Control+Enter on Windows or Command+Enter on Mac OS X).
7. Trigger the call by clicking the Details button.

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 (eVar1 as v1 and prop2 as 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 v1.

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:

• Read the user manual for the Adobe SiteCatalyst extension for Flash Professional CS5
• Visit the developer community website to find useful information about SiteCatalyst APIs and implementation
• Read the Omniture blogs to learn about best practices and product updates

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.