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
- func AcceptsGzip(r *http.Request) bool
- func Campaign(query url.Values) (source, medium, campaign string)
- func Channel(referrer, source, medium string) string
- func Clip(s string, n int) string
- func Country(zone string) string
- func Gzip(body io.ReadCloser) io.ReadCloser
- func Inject(body io.ReadCloser) io.ReadCloser
- func Injectable(res *http.Response) bool
- func Language(tag string) string
- func PagePath(u *url.URL) string
- func PolicyAllows(header http.Header) bool
- func ReferrerHost(referrer, host string) string
- func Script() ([]byte, string)
- type Agent
- type Payload
Constants ¶
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>` )
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.
const ( DeviceDesktop = "desktop" DeviceMobile = "mobile" DeviceTablet = "tablet" )
Variables ¶
This section is empty.
Functions ¶
func AcceptsGzip ¶
AcceptsGzip reads the client's Accept-Encoding.
func Campaign ¶
Campaign reads the UTM parameters, with the common ?ref= as the source when utm_source is absent.
func Country ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
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 ¶
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 ¶
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.