├── .gitignore
├── LICENSE
├── README.md
├── app.yaml
├── ga-beacon.go
├── page.html
└── static
├── badge-flat.gif
├── badge-flat.svg
├── badge.gif
├── badge.svg
├── favicon.ico
└── pixel.gif
/.gitignore:
--------------------------------------------------------------------------------
1 | *.6
2 | *.8
3 | *.o
4 | *.so
5 | *.cgo?.*
6 | _cgo_*
7 | _test*
8 | *.out
9 | _obj
10 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | The MIT License (MIT)
2 |
3 | Copyright (c) 2014 Ilya Grigorik
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Google Analytics Beacon [](https://github.com/igrigorik/ga-beacon)
2 |
3 | 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:
4 |
5 | * [Using a Beacon Image for GitHub, Website and Email Analytics](http://www.sitepoint.com/using-beacon-image-github-website-email-analytics/)
6 | (also see FAQ below regarding GitHub)
7 | * [Tracking Google Sheet views with Google Analytics using GA Beacon](http://mashe.hawksey.info/2014/02/tracking-google-sheet-views-with-google-analytics/)
8 |
9 | ### Can I use this production?
10 |
11 | The ga-beacon.appspot.com 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.
12 |
13 | Deploying your own instance is trivial: fork this repo, modify the project name in app.yaml, and follow the [normal GAE deploy instructions](https://cloud.google.com/appengine/training/go-plus-appengine/deploy). You should be up and running in less than five minutes.
14 |
15 | ### Setup instructions
16 |
17 | First, log in to your Google Analytics account and [set up a new property](https://support.google.com/analytics/answer/1042508?hl=en):
18 |
19 | * Select "Website", use new "Universal Analytics" tracking
20 | * **Website name:** anything you want (e.g. GitHub projects)
21 | * **WebSite URL: https://ga-beacon.appspot.com/**
22 | * Click "Get Tracking ID", copy the `UA-XXXXX-X` ID on next page
23 |
24 | Next, add a tracking image to the pages you want to track:
25 |
26 | * _https://ga-beacon.appspot.com/UA-XXXXX-X/insert/any/path_
27 | * `UA-XXXXX-X` should be your tracking ID
28 | * `insert/any/path` is an arbitrary path. For best results specify a meaningful and self-descriptive path. You have to do this manually, the beacon won't automatically record the page path it's embedded on.
29 |
30 | Example tracker markup if you are using Markdown:
31 |
32 | ```markdown
33 | [](https://github.com/igrigorik/ga-beacon)
34 | ```
35 |
36 | Or RDoc:
37 |
38 | ```rdoc
39 | {}[https://github.com/igrigorik/ga-beacon]
40 | ```
41 |
42 | 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!
43 |
44 | You may also auto-calculate the tracking path based in the "referer" information of the image. To activate this simple add `?useReferer` to the image URL (or `&useReferer` if you need to combine this with the `?pixel`, `?flat` or `?flat-gif` parameter). Although they are some odd browsers that don't always send the referer header, the amount of traffic coming from those browsers is usually not relevant at all. Of course that if you need to measure the traffic from those odd browsers you should not use this method.
45 |
46 | ### FAQ
47 |
48 | - **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.
49 |
50 | - **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.
51 |
52 | - **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.
53 |
54 | - **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.
55 |
56 | - **Can I use this to track visits to my GitHub README and other GitHub-served content?** No, you cannot - see https://github.com/igrigorik/ga-beacon/commit/6acd8627bb7be36f24f5516e9873c92719a50e55
57 |
--------------------------------------------------------------------------------
/app.yaml:
--------------------------------------------------------------------------------
1 | runtime: go113
2 |
3 | default_expiration: "1d"
4 |
5 | handlers:
6 | - url: /favicon\.ico
7 | static_files: static/favicon.ico
8 | upload: static/favicon\.ico
9 |
10 | - url: /.*
11 | script: auto
12 |
--------------------------------------------------------------------------------
/ga-beacon.go:
--------------------------------------------------------------------------------
1 | package main
2 |
3 | import (
4 | "context"
5 | "crypto/rand"
6 | "encoding/hex"
7 | "fmt"
8 | "html/template"
9 | "io/ioutil"
10 | "log"
11 | "net/http"
12 | "net/url"
13 | "os"
14 | "strings"
15 | "time"
16 |
17 | "google.golang.org/appengine/delay"
18 | )
19 |
20 | const beaconURL = "http://www.google-analytics.com/collect"
21 |
22 | var (
23 | pixel = mustReadFile("static/pixel.gif")
24 | badge = mustReadFile("static/badge.svg")
25 | badgeGif = mustReadFile("static/badge.gif")
26 | badgeFlat = mustReadFile("static/badge-flat.svg")
27 | badgeFlatGif = mustReadFile("static/badge-flat.gif")
28 | pageTemplate = template.Must(template.New("page").ParseFiles("page.html"))
29 | )
30 |
31 | func main() {
32 | http.HandleFunc("/", handler)
33 |
34 | port := os.Getenv("PORT")
35 | if port == "" {
36 | port = "8080"
37 | log.Printf("Defaulting to port %s", port)
38 | }
39 |
40 | log.Printf("Listening on port %s", port)
41 | if err := http.ListenAndServe(":"+port, nil); err != nil {
42 | log.Fatal(err)
43 | }
44 | }
45 |
46 | func mustReadFile(path string) []byte {
47 | b, err := ioutil.ReadFile(path)
48 | if err != nil {
49 | panic(err)
50 | }
51 | return b
52 | }
53 |
54 | func generateUUID(cid *string) error {
55 | b := make([]byte, 16)
56 | _, err := rand.Read(b)
57 | if err != nil {
58 | return err
59 | }
60 |
61 | b[8] = (b[8] | 0x80) & 0xBF // what's the purpose ?
62 | b[6] = (b[6] | 0x40) & 0x4F // what's the purpose ?
63 | *cid = hex.EncodeToString(b)
64 | return nil
65 | }
66 |
67 | var delayHit = delay.Func("collect", logHit)
68 |
69 | func sendToGA(c context.Context, ua string, ip string, cid string, values url.Values) error {
70 | client := &http.Client{}
71 |
72 | req, _ := http.NewRequest("POST", beaconURL, strings.NewReader(values.Encode()))
73 | req.Header.Add("User-Agent", ua)
74 | req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
75 |
76 | if resp, err := client.Do(req); err != nil {
77 | log.Printf("GA collector POST error: %s", err.Error())
78 | return err
79 | } else {
80 | log.Printf("GA collector status: %v, cid: %v, ip: %s", resp.Status, cid, ip)
81 | log.Printf("Reported payload: %v", values)
82 | }
83 | return nil
84 | }
85 |
86 | func logHit(c context.Context, params []string, query url.Values, ua string, ip string, cid string) error {
87 | // 1) Initialize default values from path structure
88 | // 2) Allow query param override to report arbitrary values to GA
89 | //
90 | // GA Protocol reference: https://developers.google.com/analytics/devguides/collection/protocol/v1/reference
91 |
92 | payload := url.Values{
93 | "v": {"1"}, // protocol version = 1
94 | "t": {"pageview"}, // hit type
95 | "tid": {params[0]}, // tracking / property ID
96 | "cid": {cid}, // unique client ID (server generated UUID)
97 | "dp": {params[1]}, // page path
98 | "uip": {ip}, // IP address of the user
99 | }
100 |
101 | for key, val := range query {
102 | payload[key] = val
103 | }
104 |
105 | return sendToGA(c, ua, ip, cid, payload)
106 | }
107 |
108 | func handler(w http.ResponseWriter, r *http.Request) {
109 | c := r.Context()
110 | params := strings.SplitN(strings.Trim(r.URL.Path, "/"), "/", 2)
111 | query, _ := url.ParseQuery(r.URL.RawQuery)
112 | refOrg := r.Header.Get("Referer")
113 |
114 | // / -> redirect
115 | if len(params[0]) == 0 {
116 | http.Redirect(w, r, "https://github.com/igrigorik/ga-beacon", http.StatusFound)
117 | return
118 | }
119 |
120 | // activate referrer path if ?useReferer is used and if referer exists
121 | if _, ok := query["useReferer"]; ok {
122 | if len(refOrg) != 0 {
123 | referer := strings.Replace(strings.Replace(refOrg, "http://", "", 1), "https://", "", 1)
124 | if len(referer) != 0 {
125 | // if the useReferer is present and the referer information exists
126 | // the path is ignored and the beacon referer information is used instead.
127 | params = strings.SplitN(strings.Trim(r.URL.Path, "/")+"/"+referer, "/", 2)
128 | }
129 | }
130 | }
131 | // /account -> account template
132 | if len(params) == 1 {
133 | templateParams := struct {
134 | Account string
135 | Referer string
136 | }{
137 | Account: params[0],
138 | Referer: refOrg,
139 | }
140 | if err := pageTemplate.ExecuteTemplate(w, "page.html", templateParams); err != nil {
141 | http.Error(w, "could not show account page", 500)
142 | log.Printf("Cannot execute template: %v", err)
143 | }
144 | return
145 | }
146 |
147 | // /account/page -> GIF + log pageview to GA collector
148 | var cid string
149 | if cookie, err := r.Cookie("cid"); err != nil {
150 | if err := generateUUID(&cid); err != nil {
151 | log.Printf("Failed to generate client UUID: %v", err)
152 | } else {
153 | log.Printf("Generated new client UUID: %v", cid)
154 | http.SetCookie(w, &http.Cookie{Name: "cid", Value: cid, Path: fmt.Sprint("/", params[0])})
155 | }
156 | } else {
157 | cid = cookie.Value
158 | log.Printf("Existing CID found: %v", cid)
159 | }
160 |
161 | if len(cid) != 0 {
162 | var cacheUntil = time.Now().Format(http.TimeFormat)
163 | w.Header().Set("Cache-Control", "no-cache, no-store, must-revalidate, private")
164 | w.Header().Set("Expires", cacheUntil)
165 | w.Header().Set("CID", cid)
166 |
167 | logHit(c, params, query, r.Header.Get("User-Agent"), r.RemoteAddr, cid)
168 | // delayHit.Call(c, params, r.Header.Get("User-Agent"), cid)
169 | }
170 |
171 | // Write out GIF pixel or badge, based on presence of "pixel" param.
172 | if _, ok := query["pixel"]; ok {
173 | w.Header().Set("Content-Type", "image/gif")
174 | w.Write(pixel)
175 | } else if _, ok := query["gif"]; ok {
176 | w.Header().Set("Content-Type", "image/gif")
177 | w.Write(badgeGif)
178 | } else if _, ok := query["flat"]; ok {
179 | w.Header().Set("Content-Type", "image/svg+xml")
180 | w.Write(badgeFlat)
181 | } else if _, ok := query["flat-gif"]; ok {
182 | w.Header().Set("Content-Type", "image/gif")
183 | w.Write(badgeFlatGif)
184 | } else {
185 | w.Header().Set("Content-Type", "image/svg+xml")
186 | w.Write(badge)
187 | }
188 | }
189 |
--------------------------------------------------------------------------------
/page.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | GA account: {{.Account}}
6 |
7 |
16 |
17 |
18 |
19 |