Using a Beacon Image for GitHub, Website and Email Analytics

Bruno Skvorc
Bruno Skvorc


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?


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 “
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
, 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:
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:
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:
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.


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:
. 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 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

What is a web beacon and how does it work?

A web beacon, also known as a pixel tag or clear GIF, is a tiny graphic image, usually 1×1 pixel, that is embedded in a web page or email to monitor user behavior. It works by sending information about the user’s interaction with the web page or email back to the server. This information can include the IP address of the user’s computer, the time the content was viewed, the type of browser used, and previously set cookie values.

How can I use a web beacon for my GitHub website?

To use a web beacon for your GitHub website, you need to create a 1×1 pixel image and host it on your GitHub repository. Then, you can embed this image into your web pages using an HTML img tag. Whenever a user visits your web page, the image will be loaded, and the server will record the request, providing you with valuable analytics data.

Can I use web beacons in emails?

Yes, web beacons can be used in emails to track open rates, click-through rates, and other user behaviors. When the recipient opens the email, the web beacon sends a request to the server to download the image, providing information about the user’s interaction with the email.

Are web beacons safe to use?

Web beacons themselves are not harmful. However, they can be used to track user behavior without their knowledge, which raises privacy concerns. It’s important to use web beacons responsibly and transparently, informing users about their use and offering them the option to opt out.

How can I protect my privacy from web beacons?

To protect your privacy from web beacons, you can disable images in your email client, use a privacy-focused browser or browser extension that blocks tracking pixels, or regularly clear your cookies.

What is the difference between cookies and web beacons?

Cookies and web beacons are both used to track user behavior, but they work in different ways. Cookies are small text files stored on the user’s computer, while web beacons are tiny images embedded in web pages or emails. Web beacons often rely on cookies to function effectively.

Can web beacons track my location?

Web beacons can track your IP address, which can provide a rough estimate of your location. However, they cannot provide precise location data like GPS.

How can I analyze the data collected by web beacons?

The data collected by web beacons can be analyzed using various analytics tools. These tools can provide insights into user behavior, such as the number of page views, the duration of visits, and the effectiveness of email campaigns.

Can I use web beacons to improve my website’s performance?

Yes, the data collected by web beacons can help you understand how users interact with your website, allowing you to make informed decisions about design and content improvements.

Are there any alternatives to web beacons for tracking user behavior?

Yes, there are several alternatives to web beacons for tracking user behavior, including server logs, JavaScript-based analytics tools, and cookie-less tracking methods. However, each method has its own strengths and weaknesses, and the best choice depends on your specific needs and circumstances.