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() );
                }
        }
}

The Metrics package was designed to provide a simple, reusable, extensible and flexible interface to any web metrics package, including Google Analytics, Urchin, Omniture, WebTrends and more. It supports multiple connector management, instantiating only those registered connecters that are successful at autodetecting their environment. If a developer does not know in advance which metrics package his client is using (or whether his client might change his mind at a later time), he may safely add several connectors secure in the knowledge that the package will do the heavy lifting. Additional functionality allows you to “hot-swap” connectors should that become necessary, though I myself don’t exactly know why you’d want to do that.

At this point in time, the only connector published with this library is the UrchinConnector. Google Analytics and WebTrends will follow shortly, however due to my employers’ client agreements I find it prudent to not release connectors for API’s that are considered proprietary (such as Omniture) unless I have a formal letter granting me legal permission to do so.