Understanding reporting

With any analytic measurement it is necessary to fully understand the vendor's reporting capabilities. By doing so you as developer understand better why certain interactions are tracked and others not. More importantly, it is necessary to know what values to send when. This is key as it can become overwhelming to know what an eVar3 and a prop4 variable is and when to use them.

As soon as a developer declare a project "done and dusted" the element of surprise is priceless. Tracking always seem to be the last addition/change and for various reasons. In some scenarios there is no other way, but the immense deadline pressure can be managed by better upfront technical design and information architecture. You may wonder how you can add tracking to your site before testing and bug fixing. Logically it makes sense to do this after, but for time efficiency and cost, it can be much better to implement a foundation during the build phase, provided there is some acrhitecture done upfront of course. Adding tracking this way is also less of a pain for the developer because it means less searching for when specific events might occur after the project is done and dusted. The next section will give some tips and guidance as to how we can make it easier to add tracking to a project with minimum additional effort.

Process and design

As mentioned in the previous section, technical design upfront is key for minimising efforts when implementing tracking. So knowing what metrics is required before a project build start is equally important. There is no point in adding what you think might be useful when in actual fact there might be way more or way less. The guesing game is going to cost you. Basically, implementation during build will only work if planning is done upfront. So how do we plan tracking? The first step will be to know what metrics are required. Once you know this, you can start to plan integration into the site's architecture. There are a few ways we can do this.

Automation by inclusion in a framework
Identifying where your architecture allows for easy tracking and where it doesn't, is really useful. Automating your tracking code by including it into your existing framework or architecture will greatly speed up the process. Lets take Cairngorm for example. You might want to setup a specific CairngormEvent specifically for tracking. This event is registered with a TrackingCommand which executes the tracking call on the ActionSource component. Later we will see how this combined with a utility class can automate this process even further.

Automation by adding Eclipse templates
If you haven't discovered this little gem by now, allow me to dialate your pupils. Eclipse allows you to setup code templates. Assign a word to a piece of code and access it by Ctrl+SPACE during coding, select it and hit enter. The biggest feature left out in my opinion of Flex Builder. Here is how you do it:

• Open Eclipse
• Window » Preferences » FDT
• FDT » Editor » Templates
• New
• Name » "trackEvent"
• Description » "Creates tracking event code"
• Pattern » "var event:TrackEvent = new TrackEvent(TrackEvent.TRACK_ITEM); event.data = ${var}; CairngormEventDispatcher.getInstance().dispatchEvent( event );"
• Click OK

To use this temlpate type in trackEvent and Ctrl+SPACE. You should have some options like in Fig. (b) below. Select trackEvent and hit enter and see the result as in Fig. (c).



Fig. (a) Window » Preferences » FDT » Editor » Templates


Fig. (b) Inside code block type in the template name to use and hit Ctrl+SPACE


Fig. (c) The result code is added


Tracking design document
The tracking design document allows for quick referencing when adding new tracking. This could be anything from an Excel spreadsheet to a software programme generating what tags should be used for what metrics. Everything regarding tracking should be contained in this document. The responsibility of this differ from the parties involved but usually is the result of speaking to the client to find out what metrics they require. Thumb sucking this document will lead to red eyes, way too many Red Bulls and an upset tummy. You've been warned!

A Data analyst would be an example specialist who could draw up this document as they understand more about how data can be mapped to achieve specific results tailored towards the client needs. Omniture themselves also offer a consultancy service to get the most out of tracking your projects and analyzing the reports. Documenting what tags should be used for which variables is a great way to make sure everyone involved understands what is required.

Omniture breakdown

Omniture can be divided into two categories, basic and commerce tracking. Commerce includes basic tracking. Commerce is also known as transactional tracking.

Basic tracking consist of the following variables:

• channel
• campaign
• products
• pageName
• prop1 - 50
• hier1 - 50

Commerce tracking includes the above and the additional variables:

• eVar1 - 50
• events1 - 50

Key-value pairs are used to associated values with variables. By setting these variables on the ActionSource component instance, they will be sent when the track() method is called. It is therefor important to ensure that the values are reset appropriately everytime a request is made. In some scenarios you wouldn't reset all the values but I will explain this later in the post.

Variables prop, eVar,hier and events are all custom and bespoke to a project. When commerce tracking is done you will probably have some variables that submit the same value, like eVar3 will be the same as prop3. This is for reporting purposes and used when cross-referencing reporting is done. For example maybe you want to know how many people from a specific country accessed a product within a specific timeframe, i.e. how many users from UK accessed TV model E432 between 6AM and 10AM on Tuesdays. For this you would utilise both an eVar and prop variable.


channel
Lets look at a basic example using a sitemap diagram to explain this variable.


Sitemap diagram(a) A simple sitemap for a small website

The variable channel refers to the main site section of a page. So if you have a country selector/portal page your channel will be something like "portal". Usually some props and eVars are used to indicate sub sections depending on the size of the site.

• channel = "portal"
• channel = "home"

campaign
This variable is somewhat ambigious. The obvious assumption is that this variable indicates the campaign to be tracked. Yes and no. It does refer to a campaign but not the actual website campaign. Instead it refers to the marketing campaign ID that is used to drive traffic to your site. So any advertising that is done for your site, will pass their campaign ID with the click through URL to be tracked when your site is reached. If you want to add a campaign name for your website you can do so by prefixing your pageName value with your custom campaign name or abbreviation. Thus your website campaign becomes part of the pageName variable. This is a great example of information I could've used yesterday. Adding support for the advertising campaign requires the ID to be sent to Flash using FlashVars and then tracked at the appropriate time through Actionscript. Knowing this upfront, could solve many headaches and keyboard tantrums.

I use globalCampaign to identify the website campaign by adding this to the pageName variable. As mentioned before this is not a defined Omniture variable but a custom key-value pair defined in my tracking XML file. Campaign names for the websites are quite important as clients sometime have one account for all their sites. So this will help distinguish reporting results and could also help with reporting on the bigger picture, i.e. how all the campaign sites are doing globally individually and against each other.

products
The product ID that should be tracked. This variable can become quite complex. By complex I refer to the syntax. Specifically for something like a shopping basket. There is a specific syntax for building the product, quantity and price selected. You are required to add a semi-colon before each product ID. Also note the variable name is plural and lowercase. The option exists to add an array of items which also has a specific syntax. Omniture should be consulted for this specific syntax as the level required can differ per project. The basic value requires a semi-colon before each product ID.

• products = ";productA;productB"

pageName
The most common tracking tag of them all. A unique identifier for each "page". The reason I quote page is because Flash sites blur the lines of pages and more specifically virtual pages. But actually each event or user interaction is tracked as a "page". So you may ask how can we do that? A user dragging something on the stage is not the same as clicking on a navigation item. This is where props, eVars and events come in. Remember those bespoke values mentioned earlier. By setting these values they define the granularity to which you will be able to do reporting, i.e. identifying site and subsection tracking as oppose to specific user interaction.

prop 1 - 50
Props are custom values used for requirements dictated by the project and client. This could be anything from site sections to flash player version to country and language codes. These values should be defined, yup you guessed it, up-front. Making them up as you go along is probably not a very good idea. And keeping them the same across campaigns can be very useful for reporting. 

eVar 1 - 50
Similar to props, eVars is part of commercial metrics. It allows us to cross reference specific events to basic tracking metrics. In Lehman's terms, eVars are usually the same as props as they are used to generate reports from specific defined events. For example, you may want to report on how many users from Spain logged in yesterday, by cross-referencing eVars with events you can get this report.

events
Specific user events that require knowledge of, are indicative of user experience or meet a requirement for reporting, can be defined as custom events. Login for example could be defined as a custom event.

Naming conventions

In general it is a good idea to use naming conventions when coding, but it also is a good idea to use naming conventions for the tracking tags that will be used. The standard I use quite often depend on the client as they might have one already in place but they all adhere to the same rules. Once you have decided on one, stick with it, that is afterall the idea of a convention. No exceptions. Overall using lowercase for everything is well accepted within Omniture and makes reporting easier to use. Also, the character used as delimiter in most cases is a colon (:). Some companies use the pipe (|) character. It doesn't really matter what it is, as long as you decide on one and stick with it.

ActionSource component

The component can be downloaded from the Omniture online platform SiteCatalyst Administration Console Manager. After installation you need to drag a copy from the library to your SWF (AS2) and give it an instance name. Before you can make any tracking requests you need to load the external SWF (OmnitureActionSource.swf) that is supplied when you download the code from the console. In AS3 there is a SWC for inclusion into your projects. The SWC can be added as a linked library in your project.

TrackingManager

I mentioned before that automation is very useful while building your site. If we add the tracking event in a Cairngorm based project, we can reduce the workload required for tracking by a significant amount.


Diagram (a) Centralised tracking implementation using Cairngorm

To abstract the solution a bit futher, all calls should be made to a centralised location, this location should then execute the request to Omniture. I use Cairngorm as an example as it illustrates this solution best. An event is fired whenever you need to track an item and the TrackingCommand executes the request via some utility class. But this rule will count towards any framework. I have been using an XML based solution in conjunction with a utility class called TrackingManager for a while now. There are a few pre-conditions for using this class:

• Tracking XML file should be fully loaded
• For AS2: The external file OmnitureActionSource.swf mut be loaded
• For AS3: ActionSource.swc must be added to your classpath
  

The way it works
The xml file contain key-value pairs and rulesets (settings). The rulesets are used to specify rules to use when populating specific key-value pairs. When creating the track item in the XML we specify a collection of the key-value pairs we want to be included when this item is tracked. Each of these variables specified can, but doesn't have to have a rule associated with it. If no rule is specified the value specified in track item will be used. If a rule is specified the value will be populated using the ruleset. Throughout the XML the keys are identified by the id attribute and the value is the CDATA text. The TrackingManager breakdown of execution is as follows:

• init() is called passing loaded tracking XML
• TrackingManager instantiates internal object and adds all key-value pairs with type static (This static type should not be confused with the class modifier private static, this refers to the key-value pairs)
• trackOmniture() is called
• key-value pair collection is stored to internal object seperately
• if doTrack is omitted or set to true the ActionSource track method is called passing the generated strings as per the rulesets defined in the XML

Before we look at the code lets look at the make-up of the XML file. For simplicity sake we will look at the setup with tracking one item.

<?xml version="1.0" encoding="utf-8"?>
<content>
	<tracking type="omniture">
		<account_settings>
			<item id="actionSource"><![CDATA[aSource]]></item>
<item id="acount"><![CDATA[accountTest]]></item>
			<item id="charSet"><![CDATA[UTF-8]]></item>
			<item id="currencyCode"><![CDATA[GBP]]></item>
			<item id="trackClickMap"><![CDATA[true]]></item>
<item id="visitorNamespace"><![CDATA[test]]></item>
			<item id="dc"><![CDATA[112]]></item>
		</account_settings>
		<static>
			<item id="globalCampaign"><![CDATA[ts]]></item>
		</static>
		<settings id="pageName">
			<item id="globalCampaign" />
			<item id="channel" />
			<item id="pageName" />
		</settings>
		<settings id="channel">
			<item id="globalCampaign" />
			<item id="channel" />
		</settings>
		<settings id="prop">
			<prop id="prop2">
				<item id="globalCampaign" />
				<item id="channel" />
				<item id="prop2" />
			</prop>
			<prop id="prop3">
				<item id="globalCampaign" />
				<item id="channel" />
				<item id="prop2" />
				<item id="prop3" />
			</prop>
		</settings>
		<track_item id="home" type="page">
			<item id="channel"><![CDATA[home]]></item>
			<item id="pageName"><![CDATA[home]]></item>
			<item id="prop2" group="prop"><![CDATA[home]]></item>
			<item id="prop3" group="prop"><![CDATA[]]></item>
			<item id="eVar1" group="eVar"><![CDATA[]]></item>
			<item id="eVar2" group="eVar"><![CDATA[home]]></item>
			<item id="eVar3" group="eVar"><![CDATA[]]></item>
			<item id="event1" group="event"><![CDATA[event1]]></item>
			<item id="event3" group="event"><![CDATA[event3]]></item>
		</track_item>
</tracking>
</content>

AS2
TrackingManager.getInstance().init( trackingXML, _level0 );
TrackingManager.trackOmniture("home");

Result trace:
-------------- TRACK ITEM: ts:home --------------
channel = ts:home
prop2 = ts:home:home
prop3 = ts:home:home
eVar2 = home
pageName = ts:home:home
events = event1,event3
trackOmniture() - type: page, pageName: home, delay: undefined

AS3
TrackingManager.getInstance().init( trackingXML, this );
TrackingManager.trackOmniture("home");

Result trace:
-------------- TRACK ITEM: ts:home:home --------------
channel = ts:home
prop2 = ts:home:home
prop3 = ts:home:home
eVar2 = home pageName = ts:home:home
events = event1,event3
sendOmnitureTrack() - type: page, pageName: home, delay: 0

Settings
The account settings are defined when the code is generated. This detail will be included in the code download by the SiteCatalyst Administration Console Manager. The individual settings node is what the TrackingManager class use to generate the string value set to each variable. The value for channel will be made up of globalCampaign + channel as per the settings for the channel variable.

Static vs dynamic settings
The TrackingManager distinguishes between static and dynamic values. What this means is that static values specified in the XML will never be deleted or reset. This is useful if you have a variable that will always be the same value throughout your site like globalCampaign.

Internal state
The TrackingManager retains internal state, i.e. it stores all the values set from XML in a static object. The object groups the values to "static" or "dynamic". As mentioned before static values will never be reset even if you call the resetData() method is invoked.

Resetting internal data Object
The data object will retain its values unless you explicitely call resetData() or pass in true when calling the trackOmniture() method. For more info see the API doc info below.

Overriding specific variables manually
You can override specific variables manually by submitting the initObject parameter when calling the trackOmniture() method. This object will be in the format obj = {key:value};. You can download the tracking manager with example XML here:

• AS2: TrackingManager
  
• AS3: TrackingManager