Tracking Flash Interactions

This article describes Webtrends support for Adobe Flash tracking and answers common questions about implementing Flash tracking on your web site. If you use Webtrends On Demand, or if you use SmartSource Data Collector (SDC) to log hits to your web pages, you can track Flash events by embedding an ActionScript call to dcsMultiTrack in your Flash images. This call can include Webtrends parameters that identify the event as a call to a non-page view event.

Tracking Flash Without dcsMultiTrack

If your site cannot support JavaScript, or if you have another reason for not using dcsMultiTrack, you can make a direct call to the Webtrends data collection server (or SDC) using server-side coding. For more information, Webtrends On Demand users can see “Server-Side Integration for Webtrends On Demand” in the Webtrends On Demand Implementation Guide.

What Flash Events Can Webtrends Track?

Any event in Flash can trigger a dcsMultiTrack call. For example, many companies who use Webtrends have successfully tracked clicks, video completions, slide views, and loading percentage indicators that occur within Flash. Using the general syntax for calling dcsMultiTrack within Flash, you can execute this code on any event you want to track.

Flash tracking is almost infinitely customizable. However, advanced Flash interactions require more complex tracking.

How Does Webtrends Track Flash Events?

Because Flash files are typically embedded as an object in Web content, most Web servers do not record a visitor’s interaction with a Flash file. Browsers that include the Flash plug-in recognize the file type and launch the Flash application. After the Flash file loads, interaction with the application remains local to the Web client's machine and does not typically generate hits to the content provider’s Web server log file.

To track Flash interactions, you must:

1. Add an ActionScript event tracking function to the Flash file.
2. Inside the function you created in step 1, add a call to dcsMultiTrack.
3. Call the Action Script function to record the desired Flash events.
4. Ensure that the dcsMultiTrack function is included in your Webtrends JavaScript tag. dcsMultiTrack is included in your tag by default if you created it using the Webtrends Tag Builder. For more information, see “Tracking Complex Web Page Interactions Using dcsMultiTrack.”

GetURL and ExternalInterface

For most web site implementations, embedding a call to dcsMultiTrack in your Flash presentation is the most effective way to track Flash activity. There are two primary methods of tracking Flash traffic with an embedded call, getURL and ExternalInterface. Currently, the ExternalInterface method is preferred for Webtrends tracking.

Comparing getURL and ExternalInterface

The table below provides a comparison of the advantages and disadvantages of using getURL or ExternalInterface.

Comparison of getURL and ExternalInterface Methods

Using Flash with getURL

To log a virtual page view whenever a visitor plays a particular Flash movie embedded in your page, you can activate the dcsMultiTrack function from within the ActionScript for the Flash object using getURL. This is the same functionality that is commonly used when a button within a Flash movie links to another site: the Flash object tells the page where it resides to get the URL, which in turn navigates the browser to the requested page. For example, you can insert the following code in the first frame of the Flash movie:

getURL("javascript:dcsMultiTrack('DCS.dcsuri','/Support/movie.html/','WT.ti','Support%20and%20Services%20Movie')"); 

Note that in ActionScript, this code must appear on a single line with no line break. This code does not need to be on its own layer.

You can track other Flash events in addition to plays. To capture data when a button is clicked within a Flash application, use the dcsMultiTrack function from within the event handler for that button. For example, if you have a button that plays an additional piece of video, your event handler syntax may look similar to the following example:

on (release) {
   getURL("=javascript:dcsMultiTrack('DCS.dcsuri', '/Support/ws.html/'
	  'WT.ti', 'Training%20Info%20Button', 'DCSext.type1', 'Flash')");
gotoAndPlay(2315);
}

Using this implementation, any visitor interaction that triggers a Flash event can be reported to Webtrends as a virtual page view.

Tracking Offsite URLs with getURL

One scenario that often causes difficulty for clients is tracking a Flash button that points to an off-site URL. The reason this causes difficulty is because Flash does not correctly handle two getURL calls on one event, as shown in the following example:

on(release){
getURL("javascript:dcsMultiTrack('parameter1','value1','parameter2','value2')");
getURL("http://www.Webtrends.com","_self");
}

In this case, the window navigates to the new URL, but dcsMultiTrack does not execute. To fix this problem, point the window to the new URL within the same javascript call as the dcsMultiTrack, as shown in the following example:

on(release){
getURL("javascript:dcsMultiTrack('parameter1','value1','parameter2','value2');
window.location('http://www.Webtrends.com')");

This problem only occurs when two getURL methods are called on the same event. The ExternalInterface method of Flash tracking does not experience this problem.

Using Flash with ExternalInterface

ExternalInterface is recommended because the getURL function was removed from the ActionScript language in version 3. ExternalInterface allows data to be passed in and out of the Flash object (a getURL is a static one-way command). Because of the added flexibility, this method will allow Webtrends new interactions to happen as they are developed. Further, this method allows Webtrends to continue to collect hits in Internet Explorer for lengthy parameter lists.

ExternalInterface is also especially useful for large implementations, where rewriting the dcsMultiTrack call for each button on the web site is time-consuming. In this case it makes sense to use a more modular approach. The advantage to this method is that the parameter names only need to be defined once. After definition, the values for those parameters change only when the actual click occurs. This is effective for large implementations that have many parameters that need to be passed on each click.

In ExternalInterface, the dcsMultiTrack syntax is placed in its own function within Flash. When each button calls the function, it also passes in parameters. For example, you could implement the following function on the "actions" layer of a Flash movie:

function trackEvent(value1,value2){
if (ExternalInterface.available) {
	try {
		ExternalInterface.call("dcsMultiTrack","DCS.dcsuri",
			value1,"WT.ti", value2);
			} catch (error:Error) {
			// error handling here
			} catch (error:SecurityError) {
			// error handling here
			}
	} 

While this syntax is very similar to the standard getURL syntax, it has not been executed yet. An action needs to call the function. Associate the following code with every Flash button that will be tracked:
on(release){ trackEvent('value1','value2'); }

In this case, your ActionScript syntax may look similar to the following example:

As in the getURL examples, this code can be embedded either in the first frame of a movie, or in an event handler.

Browser Support for ExternalInterface

Because ExternalInterface was introduced with Flash 8, it has the following browser compatibility:

Passing Parameters in dcsMultiTrack

When tracking Flash with dcsMultiTrack, keep in mind that any and all parameters passed to Webtrends on the initial page load (before the on-page click occurred) are inherited and included by default when the on-page click occurs. You can clear out inherited values using the dcsCleanUp function. When deciding which parameters to pass in your Flash clicks, keep in mind that these parameters should help differentiate this click from the initial page load hit.

As a best practice, use the following parameters in the dcsMultiTrack call: DCS.dcsuri and WT.ti. Passing these two parameters (and their associated values) ensures the clicks do not look like standard page views in standard page reporting.

For the DCS.dcsuri parameter, the best practice is to send a value similar to the current URI, but with a small, meaningful difference. For example, a customer clicks a download button on a products page on the /productsURI. Passing /products/button/download as the URI value identifies the click as a download rather than a page view.

For the WT.ti value, prepend a string such as Link: or Button: to the page title. This prefix easily differentiates button clicks in the Pages report.

dcsMultiTrack Call Limitations

The table below outlines the limitations for calling dcsMultiTrack via getURL and ExternalInterface. The first column outlines the number of characters, including single quotes and commas, that can be passed into the dcsMultiTrack call.

The top row of the following table outlines what browser/method is being used with a call of each particular length. Truncation occurs in Internet Explorer when the length is greater than 2048 characters, at which point the JavaScript tag cuts the string short and passes WT.tu=1 to indicate the occurrence of truncation.

dcsMultiTrack Call Limitation