Skip to content

Commit

Permalink
remove github example from readme
Browse files Browse the repository at this point in the history 
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
igrigorik committed Feb 3, 2016
1 parent 18d47bb commit 6acd862
Showing 1 changed file with 7 additions and 25 deletions.
32 changes: 7 additions & 25 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand All @@ -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
Copy link

@guypod guypod commented on 6acd862 Sep 8, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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
Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@vitr
Copy link

@vitr vitr commented on 6acd862 Sep 11, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link

@guypod guypod commented on 6acd862 Sep 11, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.