dan1978@gmx.net | My favorites ▼ | English ▼ | Sign out
Skip to page content Skip to main navigation
e.g. "adwords" or "open source"

# Extending Event Tracking

This document describes the following Event Tracker wrapper libraries that are available for download:

- `TimeTracker()`
- `MouseOverTracker()`

These samples illustrate how to extend Event Tracking via reusable wrappers to easily implement site-wide Event Tracking for common web objects. You can save these files to a script directory and reference the script from the `<head></head>` section of your HTML page.

NOTE: All samples fall under the Apache2 license.

## TimeTracker

The time tracker example demonstrates the wrapper logic required for tracking elapsed time durations. Its two primary features are:

- recording duration
- creating histograms for elapsed time segments

In its most basic implementation, `TimeTracker()` creates a category with the name "TimeTracker," records a start and end time, computes the difference, and sends that value to the Google Analytics reports. The resultant reports show the average time duration for the "TimeTracker" category, how many of these measurements were taken, and displays a histogram of default time values as the various Actions for that category.

For added functionality, you can specify your own histogram values to `TimeTracker()`. You implement this by passing in a list of milliseconds, which then delineates the histogram segments as the various Actions for that category. The `TimeTracker()` library classifies the tracked duration into one of these buckets, and records the range of values as the name for the bucket. Finally, you can also specify custom start and end times rather than using the default current time, for those cases where you need additional logic.

You can use event tracking to monitor latency for average page loads, video load times, Flash interface set up times, or even to gather average latency statistics for scripts embedded in your site.

### Functions

Name | Description
--- | ---
`TimeTracker(opt_buckets_array)` | The constructor that returns a new time tracker. You can pass in the histogram buckets here as an option to specifying them in `_setHistogramBuckets()`.
`_recordStartTime(opt_time)` | This method records the start time for computing elapsed duration. Optionally, you can use a user-specified value.
`_recordEndTime(opt_time)` | This method records the stop time for computing elapsed duration. Optionally, you can use a user-specified value.
`_setHistogramBuckets(buckets_array)` | The passed-in array specifies the cut-off points that separate out buckets. For example, if the array is `[10, 20, 50]`, then the buckets will be: <10ms, 10-19ms, 20-49ms, >50ms. If the histogram buckets are not set, then the default set of historgram values are used: `[100, 200, 300, 400, 500, 1000, 1500, 2000, 2500, 5000]`
`_getTimeDiff()` | This gets the current time difference between the start and end time for this tracker, as an option to use for other applications.

`_track(tracker, opt_event_object_name, opt_event_label)`

This method makes makes the actual call to the specified GA Tracker object. You must ensure that the start and stop time are recorded before calling `_track()`.

- `tracker` should be the default Google Analytics tracker object instantiated for your pages (e.g. `pageTracker`).
- `opt_event_object_name` TimeTracker defaults to reporting events under the name "TimeTracker," but you can change it here.
- `opt_event_label` You can also pass in an optional label for applying the time tracker functionality across multiple dimensions and viewing those different dimensions in the report.

### Basic Example

    <html>
    <head>
    <title>Latency Tracking Demo</title>
    </head>
    <body>
    <script type="text/javascript" src="http://www.google-analytics.com/ga.js"></script>
    <script type="text/javascript" src="http://www.example.com/scripts/time-tracker.js"></script>
    <script type="text/javascript">
    var timeTracker = new TimeTracker();
    var pageTracker = _gat._getTracker('UA-1735986-1');
    </script>
    <input type="button" value="Start Timer" onclick="timeTracker._recordStartTime();"/>
    <input type="button" value="Stop Timer" onclick="timeTracker._recordEndTime();"/>
    <input type="button" value="Track!" onclick="timeTracker._track(pageTracker, undefined, 'Manual Test');"/>
    </body>
    </html>

### Example Defining Histogram

    // somewhere at the top of the page
    var timeTracker = new TimeTracker();
    timeTracker._recordStartTime();

    // page load and setup

    // now when the page is done loading...
    timeTracker._recordEndTime();

    // Specify your own histogram "action" values
    timeTracker._setHistogramBuckets([10, 20, 50, 100, 500, 1000]);

    // assuming pageTracker is called from _gat._getTracker(account)
    timeTracker._track(pageTracker);

Back to Top

## MouseOverTracker

The `MouseOverTracker()` utility demonstrates a very simple use case where you can track only the initial mouseover on a page element. While you can always do this by attaching the event tracking call to any `onMouseOver()` event, this method is discouraged. Because the user will likely move the mouse over and out from the object many times within one pageview, your reporting numbers will likely be bloated (and therefore not parcticularly useful). Most importantly, the limits for events per session would likely be reached in that case. Hence, this wrapper tracks an initial mouseover and ignores any subsequent calls, providing you with the ability to track initial visitor mouse overs for a particular object without inflating event numbers.

### Functions

Name | Description
--- | ---
`MouseOverTracker(tracker)` | The constructor that returns a new mouse over tracker object. The `tracker` option should be the default Google Analytics tracker object instantiated for your pages (e.g. `pageTracker`).
`_trackMouseOver()` | The first time this method is called, a mouseover is tracked. Subsequent calls will do nothing.

### Example

    //  We want to track mouse overs on a video unit that has the element id "myVideoUnit".
    // assuming pageTracker is called from _gat._getTracker(account)

    var mouseOverTracker = new MouseOverTracker(pageTracker);
    document.getElementById('myVideoUnit').onMouseOver = mouseOverTracker._trackMouseOver;

Back to Top
Suggestions