Tracking IM interaction with Google Analytics

About a month ago Google announced better support for mobile web sites in Google Analytics. One of the improvements is a method for tracking visits with server side code for mobile browsers and apps that don’t support JavaScript.

Using this new mobile support, you can now add Google Analytics to your IM bots.

First download the client libraries for Google Analytics Mobile. At the time of this writing, they have libraries for PHP, Perl, JSP and ASPX included in the download. There’s a PDF file in the download that tells you how to get your mobile tracking ID. It’s just your Google Analytics account ID, but with the UA- replaced with MO-. If your Analytics ID is UA-123456-1 then your mobile ID will be MO-123456-1.

The client library includes a file that is loaded from an image tag on your mobile site and the code to build the URL for the image tag. Since we’re working in an environment that doesn’t support image tags, we’re going to build the URL and then open it with an HTTP client.

I’m going to use the PHP library, so if you’re using a different language, you’ll need to adapt these instructions a bit.

Most of the things that you’d track in web reports don’t exist in an IM session, so to make our reports more useful, we’re going to set some of the headers and environment variables manually. This is something you’ll probably want to tweak to get useful reports. I’m going to set the User-Agent to the IM network name, build a unique user ID cookie for tracking repeat visits, and set the query string to the contents of the IM message. The request URL will remain as your bot’s URL – the one IMified posts your messages to.

The PHP library has a snippet of code (snippet1.php) that’s supposed to be placed at the top of our PHP file. Place that at the top of your bot’s code. Google’s instructions also include a second snippet that’s to be placed at the bottom of the PHP page, but since we’re not using the image tags, you don’t need to do that.

You’ll need to edit the snippet after you add it, since it contains a bug. The PHP and Perl libraries don’t properly set the query string. The ASPX and JSP libraries don’t have this bug. In the PHP snippet you just added, find the lines that say …

  if (!empty($path)) {
    $url .= "&utmp=" . urlencode($path);
  }

… and change it to read …

  if (!empty($path)) {
    if (!empty($query)) {
      $path .= "?$query";
    }
    $url .= "&utmp=" . urlencode($path);
  }

Now right before the snippet you added, we’ll create a user-agent string with the network name and a cookie value that matches the format that Google sets when they create a tracking cookie. We also need to override the server environment variables for the query string so that Analytics can track the message contents.

  // Create a User-Agent string for the .
  $UA = 'IM '. $_POST['network'];
  // Create a user ID cookie based on the IM user's name and network
  $cookie = "0x" . substr(md5($_POST['user'] .'@'. $_POST['network']), 0, 16);
  // Yes, overwriting this server variable does feel dirty. But it works.
  // Set the query string to the contents of the message.
  $_SERVER["QUERY_STRING"] = $_POST['msg'];

Now right after the snippet from the PHP library, we need to build the tracking URL and call it from PHP. The library snippet includes a function, googleAnalyticsGetImageUrl() that builds a portion of the URL for you: it returns the filename and query string. If we were sticking this in an IMG tag, that would be sufficient, but since we’re going to load the tracking URL manually, we need to construct a fully-qualified base URL in the form http://example.com/some/path/ to put before the generated tracking URL.

You can easily hard code this base URL in your code. Just upload the ga.php library to your server and then hardcode in the path like so:

  $url = 'http://example.com/my/path/'. googleAnalyticsGetImageUrl(); 

For my purposes, however, I’m going to put ga.php in the same directory as my bot’s code and then construct the base URL automatically from that path. This allows me to move my bot’s code without having to edit the base URL. It also allows me to easily turn this code into an include file that I can just drop into any bot to add tracking.

Here’s the code I’m using to build the URL:

  $protocol = $_SERVER['HTTPS'] == 'on' ? 'https' : 'http';
  $port = ($_SERVER["SERVER_PORT"] == "80") ? "" : (":".$_SERVER["SERVER_PORT"]);
  $path = dirname($_SERVER['REQUEST_URI']);
  $path == '/' ? '' : $path;
  $url = $protocol .'://'. $_SERVER['HTTP_HOST'] . $port . $path .'/'. 
         googleAnalyticsGetImageUrl();

Now that the URL is built, we need to send a GET request to it. This GET request will set the cookie and the user-agent then load the URL just as if it were an image being called from a web browser. The image itself never gets displayed, but the fact that we load it means the tracking data is sent off to Google’s servers for your Analytics account.

  $options = array(
    "http" => array(
        "method" => "GET",
        "user_agent" => $UA,
        "header" => "Accept-Language: " . 
                    $_SERVER["HTTP_ACCEPT_LANGUAGE"] . "\r\n".
                    "Cookie: __utmmobile=" . $cookie . "\r\n"
        )
  );
  $data = file_get_contents($url, false, stream_context_create($options));

Now any time someone sends a message to your bot, the interaction will be sent to Google Analytics and will show up in your reports alongside your web traffic. This mechanism can be used for things besides IM – you can inject “visits” into Analytics from any server-side interaction.

Think about what you’d like to track with your bot and change the variables to suit your needs. Maybe you have a menu-based bot and you want to track which menu item is being chosen. Setting the menu’s name or path as the URL could be a good option for that. Or for a command-based bot, perhaps just putting the command name in the query string.

Related posts:

1. IMified Example – An IM bot using Google App Engine