analytics

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package analytics is the browser end of donkey's web analytics: the script donkey-gateway adds to web apps' HTML pages, and the classification that turns what a request carries into report dimensions before anything leaves the gateway — browser, OS and device from the user agent, a country from the browser's time zone, a channel from the referrer and campaign. The raw values stay in the gateway; donkey-telemetry only ever sees the results.

Index

Constants

View Source
const (
	// The script and its events are the gateway's on every host whose app
	// counts visits; with analytics off they are the app's like any other
	// path. Both carry a dot, which no app name can: /_donkey/<app> is where
	// browser connections reach a sibling, and these never shadow one.
	Prefix     = "/_donkey/"
	ScriptPath = Prefix + "s.js"
	EventPath  = Prefix + "e.json"

	// ScriptTag is what the gateway adds to <head>. defer keeps it off the
	// page's critical path.
	ScriptTag = `<script defer src="` + ScriptPath + `"></script>`
)
View Source
const (
	ChannelDirect   = "Direct"
	ChannelSearch   = "Search"
	ChannelSocial   = "Social"
	ChannelEmail    = "Email"
	ChannelPaid     = "Paid"
	ChannelAI       = "AI"
	ChannelReferral = "Referral"
)

Channels group where visits come from. A campaign's utm_medium wins over the referrer, because a paid or e-mailed link says what it is; a referrer alone is matched against well-known sites.

View Source
const (
	DeviceDesktop = "desktop"
	DeviceMobile  = "mobile"
	DeviceTablet  = "tablet"
)

Variables

This section is empty.

Functions

func AcceptsGzip

func AcceptsGzip(r *http.Request) bool

AcceptsGzip reads the client's Accept-Encoding.

func Campaign

func Campaign(query url.Values) (source, medium, campaign string)

Campaign reads the UTM parameters, with the common ?ref= as the source when utm_source is absent.

func Channel

func Channel(referrer, source, medium string) string

Channel classifies a visit's first page view.

func Clip

func Clip(s string, n int) string

Clip is clip for the gateway's free-form values (event names, properties).

func Country

func Country(zone string) string

Country is the ISO 3166 code of the country a time zone belongs to, or "" for UTC and anything unknown.

func Gzip

func Gzip(body io.ReadCloser) io.ReadCloser

Gzip compresses a body as it streams, flushing after every read so a response the app sends in pieces still arrives in pieces.

func Inject

func Inject(body io.ReadCloser) io.ReadCloser

Inject returns the body with ScriptTag added: right after the opening <head> tag, else before <body>, else after <html>. A document that already loads the script, or has none of those tags in its first scanLimit bytes, passes through unchanged. Bytes stream on as soon as the insertion point is known, so a server-rendered page that flushes early still does.

func Injectable

func Injectable(res *http.Response) bool

Injectable says the gateway may add the script to this response: a successful HTML document, in an encoding it can read, that has not asked intermediaries to leave it alone (Cache-Control: no-transform), and whose Content-Security-Policy lets a same-origin script load and send.

func Language

func Language(tag string) string

Language is a BCP 47 tag cut to language and region ("de-CH"): enough to tell audiences apart, without the long tail of variants.

func PagePath

func PagePath(u *url.URL) string

PagePath is a page's identity: its path, and the route of a hash router (#/… or #!/…). Query strings never count — they are where tokens and e-mail addresses end up.

func PolicyAllows

func PolicyAllows(header http.Header) bool

PolicyAllows reads every enforced Content-Security-Policy: each must allow a same-origin script (script-src-elem, else script-src, else default-src) and a same-origin beacon (connect-src, else default-src). 'strict-dynamic' makes browsers ignore 'self', and a nonce belongs to the app's own scripts — the gateway does not borrow it. Report-Only policies block nothing.

func ReferrerHost

func ReferrerHost(referrer, host string) string

ReferrerHost is where a visit came from: the referring host, without a leading www., or "" for none, for a link within the same site, or for anything that is not a web or app address. Paths are dropped — a search referrer's path can carry what the visitor searched for.

func Script

func Script() ([]byte, string)

Script is the browser script and its ETag.

Types

type Agent

type Agent struct {
	Browser string
	OS      string
	Device  string
	// Bot is a crawler, monitor, headless browser or HTTP library; its
	// events are dropped.
	Bot bool
}

Agent is what the reports keep of a user agent. The string itself is never exported.

func ParseUserAgent

func ParseUserAgent(ua string) Agent

ParseUserAgent classifies a user agent the way analytics needs it: a handful of families, not versions. Order matters — most browsers claim to be Chrome and Safari as well.

func (Agent) WithScreen

func (a Agent) WithScreen(width int) Agent

WithScreen corrects the device by the screen the script measured: iPads ask for desktop sites and say Macintosh, but a Mac's screen is never a tablet's. Widths are CSS pixels.

type Payload

type Payload struct {
	// Kind is pageview, event or engagement.
	Kind string `json:"k"`
	// URL is the page the event belongs to; Referrer is document.referrer on
	// a visit's first page view.
	URL      string `json:"u"`
	Referrer string `json:"r,omitempty"`
	// Name and Data are a custom event and its properties.
	Name string            `json:"n,omitempty"`
	Data map[string]string `json:"d,omitempty"`
	// Engaged is how long the page stayed visible, in milliseconds.
	Engaged  int64  `json:"e,omitempty"`
	Language string `json:"l,omitempty"`
	TimeZone string `json:"z,omitempty"`
	// Width is the screen's, in CSS pixels.
	Width int `json:"w,omitempty"`
}

Payload is what the script sends: short keys, since every page view carries one.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL