Using a Beacon Image for GitHub, Website and Email Analytics

Introduction

There are many ways to track traffic on your website. By far, one of the most popular ones is Google Analytics which, when signed up for, provides you with a tracking code embedded in a JavaScript snippet which you then include on every page you want tracked. This is a very simple and effective solution, and most other analytics providers do more or less the same thing.

Things get complicated, however, when dealing with content into which you cannot simply paste a block of working JavaScript code – for example, GitHub repositories and pages, emails, and more. Those resources do, however, support embedding images – and that's what we can take advantage of.

Beacon images

Traditionally, beacon images work like this:

  • Embed an image resource in your email/page
  • The src attribute of the image points to a URL on your server
  • The client (browser, email client) then requests the URL as usual, expecting a normal image
  • The server, instead of directly serving the image, first goes through a set of instructions noting down the HTTP request's details – visitor IP, time, etc – and saving these stats into a database
  • The server then returns an image, or a fake image to make it invisible – usually a 1×1 transparent pixel (useful for example at the bottom of a text email – no point in having an actually visible image there and appear spammy).

This isn't very straightforward to implement, though, and it's nigh impossible to replicate the dashboard and detailed country stats that Google Analytics offers by default in a timeframe that makes it worthwhile.

The other aspect of beacon images, and their most common use, is emails – including them in your emails allows you to track the open vs. sent ratio. Emails could never include active JS snippets in the body, so beacon images are more or less the only solution, and the data harvested this way is unreliable at best – people with HTML off by default won't ever load the images, and will track as unopened even if they did read the email. Still, some data can be collected this way.

Wouldn't it be nice if our beacon automatically uploaded data to Google Analytics and laid it all nicely out for us in a custom dashboard?

ga-beacon

Ilya Grigorik, developer advocate and performance engineer at Google (definitely follow him if you care about your website's performance), decided to take beaconing of closed resources to another, simpler level, and solve the issue mentioned in the last paragraph. He built ga-beacon, a quick solution for implementing beacon images into absolutely any web resource along with automatic structured reporting in a custom GA dashboard.

His example uses ga-beacon for tracking the visits of his GitHub repos and pages, but it can be used for any other web resource in which you have access to content but not to source code. See a sample of the dashboard in the image below, as grabbed from the repo:

Note that due to beacon tracking being only a src request, it cannot track referrals – the actual visited page (be it GitHub or something else) does have this information, but grabbing content from the image URL is a completely separate request and, as such, does not have access to the referrer info.

Implementing ga-beacon

While there are instructions in the repo README, I believe it's best if we cover them step by step with screenshots here, so you can try it out for yourself. We'll also be implementing ga-beacon in an email message later on.

Step 1: GA account and code

If you don't have an Analytics account yet, get one here. Go into Admin, and add a new account:

Pick "Website", leave all options on default, and populate the following:

  • Account Name / Website Name: anything you want. As I'll be implementing this into my GitHub repos just like Ilya did in the example, I'll pick "GitHub projects" as the name.
  • Website: as per instructions, put "https://ga-beacon.appspot.com/"

Get the tracking code by finishing the process and accepting the license agreement that pops up.

Up until this step, the procedure was identical to what you would do if you were setting up a regular website for tracking, for which you have source access. In fact, the code produced on the next screen can be pasted into any website's source, and it will do full and proper tracking – referrals and all. We, however, only need the tracking ID. Copy this tracking ID now.

Before adding the beacon image to our properties, let's first install a custom dashboard to our GA account. Custom dashboards are pre-configured layouts and styles for displayed data, saved as templates for others. The custom dashboard can be installed from this link. In the dropdown offered in the popup, select the newly created property and its "All Website Data" option.

The default dashboard will now be replaced by the custom dashboard. If not, see the Dashboard menu in the left sidebar and select this custom dashboard there.

We're ready to implement the beacon image into our pages now.

For this example, I'll be adding the beacon to my ChromeSkel_a repo. It's a bit outdated now, haven't played with it for a while, but it still seems to be getting some traffic and I'm interested in that. I don't even need to clone, edit and push – I can make the change on-the-fly through the Edit button.

I add the MarkDown syntax for images, ![](http://image/url) and use https://ga-beacon.appspot.com/UA-XXXXX-X/your-repo/page-name, where UA-XXXXX-X is the Tracking ID from before, and your-repo/page-name is an arbitrary path used to group data better in the GA dashboard. Put together, the text I added to my README file in the repo I mentioned above is:

[![Analytics](https://ga-beacon.appspot.com/UA-46899860-1/chromeskel_a/readme)](https://github.com/igrigorik/ga-beacon)

and produces the following badge:

If you'd rather the badge not be visible, you can add a no-value query param ?pixel to the URL like so:

[![Analytics](https://ga-beacon.appspot.com/UA-46899860-1/chromeskel_a/readme?pixel)](https://github.com/igrigorik/ga-beacon)

This then makes the beacon image a 1×1 transparent pixel. See below image – the badge is not visible, but the dev tools show us it's obviously there.

I prefer the badge, so I'll leave it without the ?pixel param.

That's it. ga-beacon is now installed in the README page. We can now save and commit this, and everyone accessing the root page of the chromeskel_a repo will be logged and visible in our new GA dashboard. If I refresh the page now and look at the dashboard while keeping the page open, I'm registered as an "Active Visitor".

E-mail implementation

Using ga-beacon in emails is just as straightforward as using it on websites and GitHub pages. First, make a new GA property, again a website, and this time give it a name of "My newsletter" or something of the like.

The dashboard from before is already installed, so no need to set that up. Grab the Tracking ID, and start writing an email. Include a picture inline – and give it the same URL from before, only change the tracking code and the path – the path can be the email subject, the title of the newsletter campaign, or whatever else you see fit. For example, I used this URL:

https://ga-beacon.appspot.com/UA-46899888-1/my_newsletter?pixel

This time, we're using the ?pixel param because we want the image to remain invisible. The email might have nothing to do with what the badge represents, and it might look suspicious or bad to the end user reading it if visible.

Now, send the email to several recipients (with their prior permission, of course), and observe the dashboard. If all goes well, you should see the "visit" count go up. You can modify the widgets in the dashboard to say "Opened" instead of "Visit", etc.

If you're sending multiple newsletter campaigns, you can just change the path part of the URL, and it will be reflected in the dashboard – no need to get a new Tracking ID.

Conclusion

Beacon images are incredibly useful for tracking stats where stats are not usually trackable. They help us stay on top of our audience, and assist us in improving our online presence. This article covered one of the easiest methods of implementing beacon images in your content and analyzing the received data with Google Analytics. Give it a try, and leave any feedback in the comments below!

Edit: Just moments after this article was written, GitHub introduced actual analytics: https://github.com/blog/1672-introducing-github-traffic-analytics. Regardless, you can still use this approach to track visits to any other resources where you might have control over content, but not over source code – if you’re a guest blogger somewhere, in emails, or if you have a Ghost.org blog which doesn’t yet allow custom editing of source files, etc.

Free book: Jump Start HTML5 Basics

Grab a free copy of one our latest ebooks! Packed with hints and tips on HTML5's most powerful new features.

  • http://igvita.com/ Ilya Grigorik

    Awesome writeup Bruno!

    The only other thing I’ll add is that the ga-beacon source code on GitHub is a Go application that you’re more than welcome to deploy in your own GAE account: you can use the provided/deployed ga-beacon.appspot.com instance for free, but if for whatever reason, you wish to run your own, then that should be as easy as creating a new project and pushing it to GAE.

    • http://www.bitfalls.com/ Bruno Skvorc

      Excellent, thanks for the heads up!

  • Vinoth Kumar

    Thanks for write up, much useful :) I guess the URL provided for the github blog is broken.

    • http://www.bitfalls.com/ Bruno Skvorc

      Fixed, sorry!

  • dmcclure

    Can the URL be customized to pass traditional campaign parameters (source, medium, name) or other things like I might do with a tracking event (categories, actions, labels)?

    My first pass in using this looks like I get some “false positives” due to the image being rendered when I add it to my emails prior to sending. Other than that I look forward to using this!

  • Hristian Kambourov

    Thanks for the writeup Bruno.

    Quick question: can you use the ga-beacon to track Geo location and device type of open emails?

    Thanks

    • http://www.bitfalls.com/ Bruno Skvorc

      Yep. Just look at the other parts of the Google Analytics dashboard, other menus will contain this info.

      • Hristian Kambourov

        Thanks Bruno, but maybe I wasn’t clear enough. I know Google Analytics can show Geo and Device Type.

        Recently, Gmail started caching email images on their server and loading them by default for the receiver.

        After the image is cached Google always reports back the same Location/Device.

        Any ideas about the caching and ga-beacon?

  • http://www.bitfalls.com/ Bruno Skvorc

    It warrants some playing around, I haven’t tested in production. The dashboard might be misconfigured or some such – perhaps have a look at the raw (non dash) data and see what kind of input you’re getting. Any kind of input can then probably be parsed to give you the data you need.

  • http://www.bitfalls.com/ Bruno Skvorc

    Attaching it inline is exactly what that does – it parses in the body. So yes, you can use it as an img tag directly in an HTML email.