Using the Metrics Package to record Flash Application Analytics

Web analytics is a way in which individual visitor action can be easily tracked within a site, and the aggregate statistical data derived from this can often lend remarkable insights into the effectiveness of your design, how ‘sticky’ your content is, and what your users are actually looking for. Unfortunately, extending this paradigm into flash has always been tricky, because it doesn’t adhere to the page-based paradigm on which most Analytics packages are built. Once a flash application or widget is loaded, the server loses most knowledge about what the user is actually doing within it.

Usually this isn’t really a problem- flash applications have not been too complex and not many people care where on the banner you clicked, just that you left the site as a result. Yet now with the strong growth of Flex and Ajax our web applications are becoming more and more complex, and marketers and usability experts are now demanding this tracking data in spite of the paradigm limitations.

If you really think about it, what we really are interested in tracking is a user action, rather than the page loads we are collecting right now, which means that the largest part of an analysts job is turning these page events into meaningful user actions, rather than interpreting those users. There’s been some attempt to set metrics to individual places within a page flow, yet nobody has yet thought to rethink the paradigm. But I digress…

Most Metrics providers have since opened their API’s enough to allow a developer to pretend like a new page refresh has occurred. While this is hardly optimal, it does allow us to track user events from inside of flash, but the fact that each provider has implemented their API a different way means that implementing metrics for each is still a string of unique problems to solve.

To that end I’ve written the Metrics package, which is intended to provide a common metrics proxy that any developer may use, which relies on a common library of connectors that can be swapped out as needed. In this article I go over the details of how to use it, and touch on how individual connectors might be written. You can access and download the actual library here.

Step 1: Initialize the Metrics Engine

The first step is to initialize the metrics controller with the connectors you’d like it to use.

import com.practicalflash.metrics.connectors.GoogleConnector;
import com.practicalflash.metrics.connectors.UrchinConnector;
import com.practicalflash.metrics.Metrics;

// Add the connectors
Metrics.addConnector( com.practicalflash.metrics.connectors.GoogleConnector);
Metrics.addConnector( com.practicalflash.metrics.connectors.UrchinConnector);

Note that the package can take an arbitrary number of connectors, yet will only instantiate those which successfully autodetect their environment. Should you want to deploy an application and don’t know in advance what environment you’ll be reporting to, you can hedge your bets and add several, as I have above. The only caveat is that any provided class must implement the IMetrics interface.

Step 2: Dispatch a Metrics Event

Once you’ve initialized your connector, you may dispatch metric events from any point in the application by creating a MetricsEvent object. The following example demonstrates a case where you might have an event listener waiting for a particular user action.

import com.practicalflash.metrics.MetricsEvent;

function someEventHandler( event : Event ) : void
{
        var metricEvent : MetricsEvent = new MetricsEvent("/this/is/a/test.html?foo=bar");
        metricEvent.dispatch();
}

Additional options include setting the event type, the dispatching target, or adding an arbitrary number of parameters to be parsed and passed along. Exact behavior for these parameters is described in the documentation, and may be dependent on their level of support within the various connectors.

metricEvent.target = event.target;
metricEvent.type = MetricsEvent.RECORD;
metricEvent.addParameter( "bar" , "foo" );

Further Customization

If any of the provided connectors don’t suit your purpose, the task of writing your own is actually fairly simple. The only requirement for the connector is that it implements the IMetrics interface, which prescribes two functions: detect(), which runs any autodetection script you’d care for, and send(), which should process and deliver any received information appropriately.

Additionally, the AbstractConnector class is provided with a few useful utility features, including a singleton instance of the JavascriptConnector (accessible via the jsBridge parameter) as well as getDOMBounds(), which returns an objects’ rectangular bounds with respect to the HTML DOM (just in case your metrics package supports the reporting of a page’s click area).

A sample connector might be as simple as the following:

package com.practicalflash.metrics.connectors
{
        import com.practicalflash.metrics.MetricsEvent;
        import com.practicalflash.metrics.interfaces.IMetrics;

        public class UrchinConnector extends AbstractConnector implements IMetrics
        {
                public function detect() : Boolean
                {
                        if( available )
                                return jsBridge.hasParameter( "urchinTracker" );
                        else
                                return false;
                }

                public function send( event : MetricsEvent ) : void
                {
                        jsBridge.urchinTracker( event.page + "?" + event.getURLString() );
                }
        }
}