traefik_umami_plugin

traefik-umami-plugin

Use Umami Analytics with the Traefik Reverse Proxy.

This plugin enables you to build a middleware to provide umami anytics to any web servive.

Pros:

• No need to modify the web service
• Harder to block by adblockers
• No need for JavaScript Fetching
• No need for JavaScript

Features

• Script Tag Injection - Inject the script.js as a script tag
• Script Source Injection - Inject the script.js as raw JS code
• Request Forwarding - Forward requests behind forwardingPath to th unami server
• Server Side Tracking - Trigger tracking event from the plugin, No JS needed.
• Injection when compressed - Issue, PR in progress

Installation

To add this plugin to traefik reference this repository as a plugin in the static config. The version references a git tag.

experimental:
  plugins:
    traefik-umami-plugin:
      moduleName: "github.com/1cedsoda/traefik-umami-plugin"
      version: "v1.0.2" 

[experimental.plugins.traefik-umami-plugin]
  moduleName = "github.com/1cedsoda/traefik-umami-plugin"
  version = "v1.0.2"

With the plugin installed, you can configure a middleware in a dynamic configuration such as a config.yml or docker labels. Inside traefik-umami-plugin the plugin can be configured.

Only umamiHost and websiteId options are required to get started. The middleware can then be used in a router. Remember to reference the correct provider namespace.

http:
  middlewares:
    my-umami-middleware:
      plugin:
        traefik-umami-plugin:
          umamiHost: "umami:3000"
          websiteId: "d4617504-241c-4797-8eab-5939b367b3ad"
          forwardPath: "umami"
          scriptInjection: true
          scriptInjectionMode: "tag"
          autoTrack: true
          doNotTrack: false
          cache: false
          domains:
            - "example.com"
          evadeGoogleTagManager: false
          serverSideTracking: false
          serverSideTrackingMode: "all"

[http.middlewares]
  [http.middlewares.umami.plugin.traefik-umami-plugin]
    umamiHost = "umami:3000"
    websiteId = "d4617504-241c-4797-8eab-5939b367b3ad"
    forwardPath = "umami"
    scriptInjection = true
    scriptInjectionMode = "tag"
    autoTrack = true
    doNotTrack = false
    cache = false
    domains = ["example.com"]
    evadeGoogleTagManager = false
    serverSideTracking = false

Configuration

Umami Server

Request Forwarding

Request forwarding allows for the analytics related requests to be hosted on the same domain as the web service. This makes it harder to block by adblockers. Request forwarding is always enabled.

Requests with a matching URL are forwarded to the umamiHost. The path is preserved.

• <forwardPath>/script.js -> <umamiHost>/script.js
• <forwardPath>/api/send -> <umamiHost>/api/send

Script Injection

If scriptInjection is enabled (by default) and the response Content-Type is text/html, the plugin will inject the Umami script tag/source at the end of the response body.

The data-website-id will be set to the websiteId.

There are two modes for script injection:

• tag: Injects the script tag with src="/<forwardPath>/script.js" into the response
• source: Downloads & injects the script source into the response

Server Side Tracking

The plugin can be configured to send tracking events to the Umami server as requests come in. This removes the need for JavaScript on the client side. It also allows to track pages that are not text/html or are not rendered by a browser.

However, it is not possible to track title or display values, as they are not available on the server side.

SST can be combined with script injection, but it is recommended to turn of autoTrack to avoid double tracking.

Tracked events have the name traefik.

The domains configuration is considered for SST as well. If domains is empty, all hosts are tracked, otherwise the host must be in the list. The port of the host is ignored.

The mode notinjected is useful if you want to use SST and script injection at the same time, but want to avoid double tracking. Perfect for full analytics coverage of your web service. There are two modes for server side tracking:

• all: Tracks all requests
• notinjected: Tracks all requests that have not been injected (always if scriptInjection is disabled)