I'm a numbers person.  I love taking time to dig through traffic statistics and figure out how successful a product, article, or idea really was.  On my blog I use Google Analytics to suss out the details.

But sometimes I need to track something not on a website.

One of the coolest client projects I get to work on is a server-side API.  Everything is coded in PHP, using a custom blend of scripted daemons to keep a pool of processes running to process a queue.[ref]Some day I'll be able to write up a full explanation of what's actually going on behind the scenes.  For now, just know it include multi-threaded PHP processing of asynchronous job queues spread across three different servers. In other words, "magic."[/ref]  As far as we can tell, things are moving along just fine and people are using the service frequently.

Unfortunately, we only ever hear when something goes wrong, so we don't really know how often customers are using the service.  It would be great if the same tool I use to track web usage could apply to the API - oh wait, it can!

GitHub to the Rescue

I started Google-ing around for an existing solution and stumbled upon php-ga, a "server-side Google Analytics PHP client."

The library is remarkably simple to use.  Just [cci]require()[/cci] the autoloader, create a tracker, then start applying your logic to it.  For example, the following routine could be used to track any event you'd like in WordPress:

/**
* Track a generic action in WordPress.
*
* @var string $event_name Name of the event you want to track. I.e. "Custom Event"
*/
function ga_track_event( $event_name ) {
// Get a URL-like version of the event.
$event_slug = sanitize_title( $event_name );

// Initilize GA Tracker
$tracker = new GoogleAnalytics\Tracker( 'UA-12345678-9', 'example.com' );

// Assemble Visitor information
$visitor = new GoogleAnalytics\Visitor();
$visitor?>setIpAddress( $_SERVER['REMOTE_ADDR'] );
$visitor->setUserAgent( $_SERVER['HTTP_USER_AGENT'] );

// Assemble Session information
$session = new GoogleAnalytics\Session();

// Assemble Page information
$page = new GoogleAnalytics\Page( "/custom-event/{$event_slug}" );
$page->setTitle( $event_name );

// Track page view
$tracker->trackPageview( $page, $session, $visitor );
}
add_action( 'ga_track_event', 'ga_track_event', 10, 1 );

// Elsewhere in your code, call:
do_action( 'ga_track_event', 'My Custom Event' );

We're now using this library to track specific events triggered within the API.  One example is that each invocation of the API is tracked against a unique customer hash we're already using to identify customers - this way we can track repeat "pageviews" in addition to new ones.

There is one major caveat to keep in mind - Google Analytics tracks pageviews.  You can use the library above to track either "virtual pages" (i.e. name your events as if they were pages) or track custom events.  If you're using an existing Analytics profile, I would encourage prefixing your virtual pages with something memorable (so you can filter them out from real pageviews) or using custom events instead.

Ultimately, though, the limit is that of your own imagination.