TrackingDetailsAndTricks

Tracking Details and Tricks

Manually Add Parameters to a Tracker
set( field:String, value:String )
allow you to add a permanent parameter for all following hit requests.

For example add the application name:

tracker.set( Tracker.APP_NAME, "My Game" );
tracker.screenview( "High Scores" );

setOneTime( field:String, value:String )
allow you to add a "one shot" parameter for the next hit request.

For example change temporarily the data source

tracker.setOneTime( Tracker.DATA_SOURCE, "advertising" );
tracker.screenview( "Game Over" );

add( values:Dictionary )
works like the set() method but allow you to add parameters in batch from a Dictionnary of field/value pairs.

For example define the application datas:

var gameinfo:Dictionnary = new Dictionnary();
    gameinfo[ Tracker.APP_NAME ] = "My Game";
    gameinfo[ Tracker.APP_ID ] = "com.something.mygame";
    gameinfo[ Tracker.APP_VERSION ] = "1.0.0";
    gameinfo[ Tracker.APP_INSTALLER_ID ] = "Amazon App Store";

tracker.add( gameinfo );
tracker.screenview( "Intro" );

Automatically Add Parameters to a Tracker
You can use functions and/or classes helpers like:
ApplicationInfo, SystemInfo, TimingInfo, etc.
generateFlashSystemInfo(), generateAIRSystemInfo(), generateCLISystemInfo(), etc.

For example you would want to always add the System info:

var sysinfo:SystemInfo = generateFlashSystemInfo();
tracker.add( sysinfo.toDictionary() );

Or for example you would want to dynamically generate the application info from the AIR application descriptor:

var appinfo:ApplicationInfo = generateAIRAppInfo();
tracker.add( appinfo.toDictionary() );

Throttling
Our library may throttle events, as well as other hits, if a large number of send calls are made in a short period of time.

By default our trackers use a RateLimiter

• Online SWF files (equivalent to analytics.js)
  the WebTracker starts with 20 hits
  that are replenished at a rate of 2 hits per second.
• AIR applications (equivalent to Android SDK/iOS SDK)
  the AppTracker starts with 60 hits
  that are replenished at a rate of 1 hit every 2 seconds.
• RedTamarin (command-line and server-side)
  the CliTracker starts with 100 hits
  that are replenished at a rate of 10 hits per second.

Sampling
By default our trackers use a sample rate of 100%, that means all hits are send, but then if your sites or apps reach millions of users you might consider sampling down your data to maybe 40% more or less.

By sampling the hits for your site or app, you will still get reliable report results while staying within the hit limits for your account.

see: How sampling works

Session Management

By default, Google Analytics will group hits that are received within 30 minutes of one another into the same session. This period is configurable at the property level.

see: Learn how to configure this session timeout period

Manual Session Management
You can manually start a new session when sending a hit to Google Analytics.

The following example shows how to start a new session when sending a screen view:

tracker.setOneTime( Tracker.SESSION_CONTROL, SessionControl.START );
tracker.screenview( "Home Screen" );

Automatic Session Management
Not supported yet.

Pages

Tracking pages is sending a "pageview" hit request:

tracker.pageview( "/hello/world", "Hello World" );

You can use UTF-8 in both the page path and title:

tracker.pageview( "/hello/€", "Hello €" );

Our trackers automatically add a domain name when sending a "pageview" checkout the utilities: getHostname(), getCLIHostname().

You can override the hostname this way:

tracker.set( Tracker.DOCUMENT_HOSTNAME, "www.as3lang.org" );

Modifying page URLs
In some specific cases you would want to rewrite URLs containing identifying informations, for example /user/USER_ID/account would become /user/account.

Tracking virtual pageviews
From inside an online SWF file or an AIR application when you track pageviews you are basically tracking virtual pages.

This is very similar to Single Page Application Tracking when an HTML page load content dynamically via AJAX.

Screens

Automatic Screen Measurement
Depending on how you're managing the navigation of your application you could automate the tracking of screens.

For example, you could take the convention that a screen is "visited" when a DisplayObject is added to the Stage:

public class MyScreen extends Sprite
{
    public function MyScreen()
    {
        super();

        name = "My Screen Name";

        if( stage )
        {
            onAddedToStage();
        }
        else
        {
            addEventListener( Event.ADDED_TO_STAGE, onAddedToStage );
        }
    }

    //...
    private function onAddedToStage( event:Event = null ):void
    {
        removeEventListener( Event.ADDED_TO_STAGE, onAddedToStage );
        tracker.screenview( this.name );
    }
}

Events

Use Events to collect data about interactions with your content.
See: About Events

Non-interaction events
In some cases you might want to send an event as a non-interaction event.

For example to indicate that a video autoplay (eg. without the user actually clicking the "play" button).

tracker.setOneTime( Tracker.NON_INTERACTION, "1" );
tracker.event( "Videos", "play", "Mr. Robot: Official Trailer" );

Timing

Exceptions

Caught Exceptions
Caught exceptions are errors in your app for which you've defined exception handling code, such as the occasional timeout of a network connection during a request for data.

Measure a caught exception by setting the exception field values on the tracker and sending the hit, as in this example:

try
{
    //an error is thrown here
}
catch( e:Error )
{
    tracker.exception( e.name + ":" + e.errorID, false );
}

Warning

Never send the exception message (e.message) to Google Analytics as it may contain personally identifiable information.

Uncaught Exception Measurement
Uncaught exceptions represent instances where your app encountered unexpected conditions at runtime and are often fatal, causing the app to crash.

Uncaught exceptions can be sent to Google Analytics automatically by setting a listener to the UncaughtErrorEvent.UNCAUGHT_ERROR event.

public class MyScreen extends Sprite
{
    public function MyScreen()
    {
        super();

        loaderInfo.uncaughtErrorEvents.addEventListener( UncaughtErrorEvent.UNCAUGHT_ERROR, onGlobalErrors );

        if( stage )
        {
            onAddedToStage();
        }
        else
        {
            addEventListener( Event.ADDED_TO_STAGE, onAddedToStage );
        }
    }

    //...
    
    private function onGlobalErrors( event:UncaughtErrorEvent ):void
    {
        if (event.error is Error)
        {
            var error:Error = event.error as Error;
            // do something with the error
            tracker.exception( error.name + ":" + error.errorID );
        }
        else if (event.error is ErrorEvent)
        {
            var errorEvent:ErrorEvent = event.error as ErrorEvent;
            // do something with the error
            tracker.exception( "Error:" + errorEvent.errorID );
        }
        else
        {
            // a non-Error, non-ErrorEvent type was thrown and uncaught
            tracker.exception( "unknown error occured" );
        }
        
    }
}

Custom Dimensions and Metrics

E-commerce

Note:
Our trackers can track E-Commerce Transaction and Item but it seems those will be deprecated in favour of Enhanced E-Commerce which uses more complex parameters that we don't support yet.

In fact, analytics.js need to load an additional ecommerce.js, see Ecommerce Tracking.

We may not support that at all as our focus is on the Measurement Protocol.