Permalink
Browse files

remove github example from readme

GitHub proxies both HTTP and HTTPS resources, which means the beacon does not receive all the hits. Hence, removing the GitHub example. That said, the good news is that GitHub now offers own analytics: https://github.com/blog/1672-introducing-github-traffic-analytics
  • Loading branch information...
igrigorik committed Feb 3, 2016
1 parent 18d47bb commit 6acd8627bb7be36f24f5516e9873c92719a50e55
Showing with 7 additions and 25 deletions.
  1. +7 −25 README.md
View
@@ -5,18 +5,6 @@ Sometimes it is impossible to embed the JavaScript tracking code provided by Goo
* [Using a Beacon Image for GitHub, Website and Email Analytics](http://www.sitepoint.com/using-beacon-image-github-website-email-analytics/)
* [Tracking Google Sheet views with Google Analytics using GA Beacon](http://mashe.hawksey.info/2014/02/tracking-google-sheet-views-with-google-analytics/)
### Hands-on example: Google Analytics for GitHub
_Note: GitHub [released traffic analytics](https://github.com/blog/1672-introducing-github-traffic-analytics) on Jan 7, 2014 and provides deeper analytics (e.g. referrer tracking) than what is possible via GA-Beacon. If you're interested in analytics for your GitHub project, use that... That said, if you want real-time analytics, or want to see a demo of what's possible with a tracking pixel, see below._
[![GA Dashboard](https://lh5.googleusercontent.com/-Zu9r9m7Uv0c/UsSQlJ5OoeI/AAAAAAAAHwo/fvH_lrVUV0w/w1007-h467-no/skitch.png)](https://lh5.googleusercontent.com/-Zu9r9m7Uv0c/UsSQlJ5OoeI/AAAAAAAAHwo/fvH_lrVUV0w/w1007-h467-no/skitch.png)
**Curious which of your GitHub projects are getting all the traffic, or if anyone is reading your GitHub wiki pages?** Well, that's what Google Analytics is for! GitHub does not allow us to install arbitrary analytics, but we can still use a simple tracking image to log visits in real-time to Google Analytics - for full details, follow the instructions below. Once everything is setup, install [this custom dashboard](https://www.google.com/analytics/web/template?uid=MQS4cmZdSh2OWUVqRntqXQ) in your account for a nice real-time overview (as shown in above screenshot).
_Note: GitHub proxies all assets through their own fetch service. As a result, while you can still use the tracking pixel, the fetch service acts as an intermediary that (intentionally, in this case) hides a lot of information: visitors IP address, does not store cookies, etc. As a result, each hit will be counted and reported as a unique visitor in GA._
### Setup instructions
First, log in to your Google Analytics account and [set up a new property](https://support.google.com/analytics/answer/1042508?hl=en):
@@ -28,37 +16,31 @@ First, log in to your Google Analytics account and [set up a new property](https
Next, add a tracking image to the pages you want to track:
* _https://ga-beacon.appspot.com/UA-XXXXX-X/your-repo/page-name_
* _https://ga-beacon.appspot.com/UA-XXXXX-X/insert/any/path_
* `UA-XXXXX-X` should be your tracking ID
* `your-repo/page-name` is an arbitrary path. For best results specify the repository name and the page name - e.g. if you have multiple readme's or wiki pages you can use different paths to map them to same repo: `your-repo/readme`, `your-repo/other-page`, and so on!
* `insert/any/path` is an arbitrary path. For best results specify a meningful and self-descriptive path. You have to do this manually, the beacon won't automatically record the page path it's embedded on.
Example tracker markup if you are using Markdown:
```markdown
[![Analytics](https://ga-beacon.appspot.com/UA-XXXXX-X/your-repo/page-name)](https://github.com/igrigorik/ga-beacon)
[![Analytics](https://ga-beacon.appspot.com/UA-XXXXX-X/welcome-page)](https://github.com/igrigorik/ga-beacon)
```
Or RDoc:
```rdoc
{<img src="https://ga-beacon.appspot.com/UA-XXXXX-X/your-repo/page-name" />}[https://github.com/igrigorik/ga-beacon]
{<img src="https://ga-beacon.appspot.com/UA-XXXXX-X/welcome-page" />}[https://github.com/igrigorik/ga-beacon]
```
If you prefer, you can skip the badge and use a transparent pixel. To do so, simply append `?pixel` to the image URL.
There are also "flat" style variants available, which are available when appending `?flat` or `?flat-gif` to the image URL.
And that's it, add the tracker image to the pages you want to track and then head to your Google Analytics account to see real-time and aggregated visit analytics for your projects!
If you prefer, you can skip the badge and use a transparent pixel. To do so, simply append `?pixel` to the image URL. There are also "flat" style variants available, which are available when appending `?flat` or `?flat-gif` to the image URL. And that's it, add the tracker image to the pages you want to track and then head to your Google Analytics account to see real-time and aggregated visit analytics for your projects!
### FAQ
- **How does this work?** Google Analytics provides a [measurement protocol](https://developers.google.com/analytics/devguides/collection/protocol/v1/devguide) 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](https://developers.google.com/analytics/devguides/collection/protocol/v1/reference#transport), but unfortunately we can't use that directly because we need to generate and report a unique visitor ID for each hit - e.g. GitHub does not allow us to run JS on the client to generate the ID. To address this, we proxy the request through ga-beacon.appspot.com, 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.
- **Why do we need to proxy?** Google Analytics supports reporting of visit data [via GET requests](https://developers.google.com/analytics/devguides/collection/protocol/v1/reference#transport), 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.appspot.com, 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.
- **Can I use this outside of GitHub?** Yep, [you certainly can](http://www.sitepoint.com/using-beacon-image-github-website-email-analytics/). It's a generic beacon service.
- **Do I have to use ga-beacon.appspot.com?** You can if you want to - it's free. Alternatively, feel free to deploy your own instance directly on Google App Engine. The project is under MIT license.
- **Do I have to use ga-beacon.appspot.com?** 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.

4 comments on commit 6acd862

@guypod

This comment has been minimized.

Show comment
Hide comment
@guypod

guypod Sep 8, 2016

@igrigorik per the guidance GitHub gave for badges, you can still get these beacons to not cache if you add Cache-Control: no-cache and ETag headers (see github/markup#224 (comment)).

Wouldn't that work for this beacon too?

guypod replied Sep 8, 2016

@igrigorik per the guidance GitHub gave for badges, you can still get these beacons to not cache if you add Cache-Control: no-cache and ETag headers (see github/markup#224 (comment)).

Wouldn't that work for this beacon too?

@igrigorik

This comment has been minimized.

Show comment
Hide comment
@igrigorik

igrigorik Sep 10, 2016

Owner

Ah, great find. Indeed, it would. Up for making a pull? :-)

Owner

igrigorik replied Sep 10, 2016

Ah, great find. Indeed, it would. Up for making a pull? :-)

@vitr

This comment has been minimized.

Show comment
Hide comment
@vitr

vitr Sep 11, 2016

I don't get, how is this really helping us? in the topic github/markup#224 (comment) they discuss issues with badges, e.g. if you have a new etag github will bust the cache and you can see updated badge. How does it work for the beacon? do we need to generate Etags randomly on every request? but this does not solve the core issue, in the analytics you will see github robot not the original visitor. just my $0.02

vitr replied Sep 11, 2016

I don't get, how is this really helping us? in the topic github/markup#224 (comment) they discuss issues with badges, e.g. if you have a new etag github will bust the cache and you can see updated badge. How does it work for the beacon? do we need to generate Etags randomly on every request? but this does not solve the core issue, in the analytics you will see github robot not the original visitor. just my $0.02

@guypod

This comment has been minimized.

Show comment
Hide comment
@guypod

guypod Sep 11, 2016

I did a bit more digging (was related to how we process badges). It appears you can use a very short expires header too to make most requests get through.

However, you're right that the user identity will be lost. So you can u can get counts (potentially with some inaccuracy for simultaneous visits), but not the rich client info. Still, in some scenarios that's helpful.

I'll see if I can find the time to submit a PR. Code seems simple, just need to have time to setup an app engine instance and such too.

guypod replied Sep 11, 2016

I did a bit more digging (was related to how we process badges). It appears you can use a very short expires header too to make most requests get through.

However, you're right that the user identity will be lost. So you can u can get counts (potentially with some inaccuracy for simultaneous visits), but not the rich client info. Still, in some scenarios that's helpful.

I'll see if I can find the time to submit a PR. Code seems simple, just need to have time to setup an app engine instance and such too.

Please sign in to comment.