GA Beacon

Use Google Analytics where it is usually not possible

This project was inspired by GA Beacon.

Sometimes it is impossible to embed the Javascript tracking code provided by Google Analytics: the host page does not allow arbitrary JavaScript, and there is no Google Analytics integration. However, not all is lost! If you can embed a simple image (pixel tracker), then you can beacon data to Google Analytics. For a great, hands-on explanation of how this works, check out the following guides:

Using a Beacon Image for GitHub, Website and Email Analytics (also see FAQ below regarding GitHub)
Tracking Google Sheet views with Google Analytics using GA Beacon

Can I use this production?

The ga-beacon.atanas.info instance is a demo instance, good for prototyping and proof of concepts. If you intend to use this in production for your application, you should deploy your own instance of this service, which will allow you to scale the service up and down to meet your capacity needs, introspect the logs, customize the code, and so on.

Deploying your own instance is trivial - just press the button below:

Visitor stats

Code stats

FAQ

How does this work?

Google Analytics provides a measurement protocol which allows us to POST arbitrary visit data directly to Google servers, and that's exactly what GA Beacon does: we include an image request on our pages which hits the GA Beacon service, and GA Beacon POSTs the visit data to Google Analytics to record the visit. As a result, if you can embed an image, you can beacon data to Google Analytics.

Why do we need to proxy?

Google Analytics supports reporting of visit data via GET requests, but unfortunately we can't use that directly because we need to generate and report a unique visitor ID for each hit - e.g. some pages do not allow us to run JS on the client to generate the ID. To address this, we proxy the request through ga-beacon.atanas.info, which in turn is responsible for generating the unique visitor ID (server generated UUID), setting the appropriate cookies for repeat hits, and reporting the hits to Google Analytics.

What about referrals and other visitor information?

Unfortunately the static tracking pixel approach limits the information we can collect about the visit. For example, referral information can't be passed to the tracking pixel because we can't execute JavaScript. As a result, the available metrics are restricted to unique visitors, pageviews, and the User-Agent and IP address of the visitor.

Do I have to use ga-beacon.atanas.info?

You can if you want to - it's free, but there are no capacity or availability promises. For best results, deploy your own instance directly on Google App Engine: clone this repository, change the project name, and deploy your own instance - easy as that. The project is under MIT license.

Usage

GA Beacon is a serverless Node JS function deployed and running on Vercel's network. It can be found here.

In order to capture a pageview event in Google Analytics, several required arguments need to be passed:

Google Analytics ID (account) - usually starts with UA- and is followed by a series of numbers.
Page: (page) - the page to be captured.
Pixel (pixel) - Optional boolean argument which tells the module to return a blank 1x1 pixel SVG image
Flat (flat) - Optional boolean argument which tells the module to return a flat SVG badge image

If either of the flat and pixel optional arguments is missing, the module will return the default SVG badge image.

Examples

Example URL

The URL below sends pageview event for the "github.com/scriptex/ga-beacon" to Google Analytics for the "UA-83446952-1" ID and returns an embeddable SVG image - blank 1x1 pixel SVG image.

https://ga-beacon.atanas.info/api/analytics
?account=UA-83446952-1
&page=github.com/scriptex/ga-beacon
&pixel

Example tracker markup (in Markdown)

[![Analytics](https://ga-beacon.atanas.info/api/analytics?account=UA-83446952-1&page=github.com/scriptex/ga-beacon&flat)](https://github.com/scriptex/ga-beacon)