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.

Frequently Asked Questions (FAQs) about Using Beacon Image for Website and Email Analytics