google-analytics-proxy

README

Google Analytics Proxy

📈 Transparent HTTP proxy for tracking pageviews with Google Analytics

Motivations

There are a number of situations where it is difficult (or impossible) to utilize the traditional Google Analytics tracking scripts.

• Server-side problems
  • What if the page is dynamically generated, or the contents isn't under your direct control?
  • What if the page return an HTTP redirect?
  • What if the page returns non-HTML content?
• Client-side problems:
  • What if the browser blocks Google Analytics?
  • What if the browser has JavaScript disabled?
  • What if the browser doesn't even use JavaScript (like curl)?

This application is an option to solve all of these problems.

What this application is not

• A proxy for https://www.google-analytics.com/collect.
• A proxy for serving analytics.js.
• A JavaScript library.

How it works

This application is an HTTP proxy server; It listens for a client HTTP request, forwards the request to an upstream HTTP server, waits for a response from the upstream server, and finally returns that response back to the original client.

From the client's perspective everything is functioning identically to if they were connecting to the upstream directly, but all of their traffic is actually being transparently proxied.

While this is happening, each request and response is used to construct a pageview event, that is then reported to Google Analytics.

Since there is no JavaScript whatsoever, it is not possible to disable Google Analytics reporting. 🚫

Additionally, the upstream HTTP service doesn't need to integrate with (or have any knowledge of) Google Analytics.

Installing

A release version Docker image can be pulled by running:

docker pull ghcr.io/joshdk/google-analytics-proxy:v0.1.0

Or, a development version binary can be installed by running:

go install github.com/joshdk/google-analytics-proxy@master

Configuration

This tool uses several environment variables as configuration.

Name	Purpose	Example
$LISTEN	Host and port that the proxy will listen on.	0.0.0.0:8080
$TLS_CERT_PATH	(Optional) Path to TLS certificate file.	/path/to/tls.pem
$TLS_KEY_PATH	(Optional) Path to TLS private key file.	/path/to/tls.key
$UPSTREAM_ENDPOINT	Address of the upstream service to be proxied.	https://example.com
$UPSTREAM_HOSTNAME	(Optional) Hostname to used when proxying requests to the upstream.	example.com
$GOOGLE_ANALYTICS_TRACKING_ID	Tracking ID for your Google Analytics property	UA-123456789-1
$GOOGLE_ANALYTICS_PROPERTY_NAME	Name of your Google Analytics property.	example.com
$GOOGLE_ANALYTICS_DRY_RUN	(Optional) Disables Google Analytics reporting.	true

Usage

To run the Docker image, you can use a command like:

docker run \
  --rm \
  -p 8080:8080 \
  -e LISTEN=0.0.0.0:8080 \
  -e UPSTREAM_ENDPOINT=https://example.com \
  -e UPSTREAM_HOSTNAME=example.com \
  -e GOOGLE_ANALYTICS_PROPERTY_NAME=example.com \
  -e GOOGLE_ANALYTICS_TRACKING_ID=UA-123456789-1 \
    ghcr.io/joshdk/google-analytics-proxy:v0.1.0

Or, to run the local binary, you can use a command like:

LISTEN=0.0.0.0:8080 \
UPSTREAM_ENDPOINT=https://example.com \
UPSTREAM_HOSTNAME=example.com \
GOOGLE_ANALYTICS_PROPERTY_NAME=example.com \
GOOGLE_ANALYTICS_TRACKING_ID=UA-123456789-1 \
  $GOPATH/bin/google-analytics-proxy

Kubernetes

This application is designed to be deployed into a Kubernetes cluster, ideally as a side-car container inside the same pod as your existing web service. While not the only configuration option, this technique is beneficial because it enables you to:

• Proxy your service with minimal networking overhead.
• Scale along with your service.
• Be configured in the same deployment spec as your service.

As a demo, there is a kubernetes directory, containing a kustomize manifest which can be deployed with kubectl apply -k ./kubernetes. Afterwards, you must run kubectl port-forward svc/demo 8080:8080 in order to expose the service locally.

---

In all cases, browsing to https://localhost:8080 afterwards will display the proxied upstream. Realtime pageviews should also appear in your Google Analytics dashboard.

License

This code is distributed under the MIT License, see LICENSE.txt for more information.