Documentation
¶
Overview ¶
Package analytics renders privacy-first web analytics and search engine verification tags: Umami (cookieless), Google Analytics 4 with Consent Mode v2 denied by default, and Google Search Console verification.
Every provider is off until its env var is set: an empty Config renders nothing and adds nothing to the Content-Security-Policy. Config.Tags goes in the <head> of the root view (the "analytics" view function does it with the request's CSP nonce), and Config.CSPSources lists the exact origins each enabled provider needs.
Index ¶
- Constants
- type Config
- func (c Config) BingSiteAuthHandler() http.Handler
- func (c Config) CSPSources() map[string][]string
- func (c Config) Enabled() bool
- func (c Config) SendUmamiEvent(ctx context.Context, client *http.Client, userAgent string, e UmamiEvent) error
- func (c Config) Tags(nonce string) template.HTML
- func (c Config) Validate() error
- func (c Config) VerificationFileHandler() http.Handler
- type UmamiEvent
Constants ¶
const DefaultUmamiScriptURL = "https://cloud.umami.is/script.js"
DefaultUmamiScriptURL is the Umami Cloud tracker.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// UmamiWebsiteID enables Umami (the website ID from its dashboard).
UmamiWebsiteID string `env:"UMAMI_WEBSITE_ID"`
// UmamiScriptURL is the tracker script, Umami Cloud by default; point
// it at a self-hosted instance's /script.js. Empty uses
// DefaultUmamiScriptURL.
UmamiScriptURL string `env:"UMAMI_SCRIPT_URL" default:"https://cloud.umami.is/script.js"`
// UmamiHostURL sends the events to another origin than the script's
// (data-host-url).
UmamiHostURL string `env:"UMAMI_HOST_URL"`
// UmamiDomains limits tracking to these hostnames (data-domains), so
// staging and localhost stay out of the stats.
UmamiDomains []string `env:"UMAMI_DOMAINS"`
// UmamiTag groups the events under a tag (data-tag), e.g. an A/B
// variant.
UmamiTag string `env:"UMAMI_TAG"`
// UmamiIgnoreDoNotTrack tracks visitors whose browser sends Do Not
// Track; by default they are not tracked (data-do-not-track).
UmamiIgnoreDoNotTrack bool `env:"UMAMI_IGNORE_DO_NOT_TRACK"`
// GAMeasurementID enables Google Analytics 4 (G-XXXXXXX).
GAMeasurementID string `env:"GA_MEASUREMENT_ID"`
// GAConsentDefaultGranted starts with every Consent Mode signal
// granted and loads gtag.js on the first page. Leave it off where
// LGPD/GDPR apply: the app must ask first (window.vukemAnalytics.consent).
GAConsentDefaultGranted bool `env:"GA_CONSENT_DEFAULT_GRANTED"`
// GoogleSiteVerification renders one google-site-verification meta tag
// per token (Search Console, "HTML tag" method).
GoogleSiteVerification []string `env:"GOOGLE_SITE_VERIFICATION"`
// GoogleSiteVerificationFiles serves each file name (google<token>.html,
// Search Console "HTML file" method) at the site root.
GoogleSiteVerificationFiles []string `env:"GOOGLE_SITE_VERIFICATION_FILES"`
// BingSiteVerification renders one msvalidate.01 meta tag per token
// (Bing Webmaster Tools, "Meta tag" method) and lists them in
// /BingSiteAuth.xml ("XML file" method).
BingSiteVerification []string `env:"BING_SITE_VERIFICATION"`
}
Config selects the providers. Load it from the environment with config.Load; the zero value disables everything.
func (Config) BingSiteAuthHandler ¶
BingSiteAuthHandler serves /BingSiteAuth.xml, the Bing Webmaster Tools "XML file" verification listing every BingSiteVerification token. vukem registers it when BING_SITE_VERIFICATION is set.
func (Config) CSPSources ¶
CSPSources returns the directive sources the enabled providers need, for middleware.SecureHeadersConfig.CSPSources (vukem's stacks add them), or nil when no script provider is on.
func (Config) SendUmamiEvent ¶
func (c Config) SendUmamiEvent(ctx context.Context, client *http.Client, userAgent string, e UmamiEvent) error
SendUmamiEvent posts e to Umami's /api/send, for events the browser never sees (a webhook, a job). It is a no-op when Umami is off. Umami drops requests whose User-Agent looks like a bot: pass the visitor's. A nil client uses one with a 10s timeout.
func (Config) Tags ¶
Tags returns the head elements of the enabled providers, with nonce on every script ("" omits it). Every value is escaped, validated or not.
func (Config) Validate ¶
Validate refuses values that are not what the providers issue. Call it at boot (vukem.New does): a typo fails the deploy instead of silently dropping the stats.
func (Config) VerificationFileHandler ¶
VerificationFileHandler serves the GoogleSiteVerificationFiles at the site root ("GET /google<token>.html") with the content Search Console checks, and 404 for any other path. vukem registers it for each file.
type UmamiEvent ¶
type UmamiEvent struct {
// Name is the event name (required, at most 50 characters).
Name string
// URL is the page path the event belongs to, e.g. "/checkout".
URL string
// Hostname is the site's host, e.g. "example.com".
Hostname string
// Title, Referrer and Language describe the page and visitor
// (optional).
Title, Referrer, Language string
// Data holds the event properties (optional).
Data map[string]any
}
UmamiEvent is a custom event sent from the server with Config.SendUmamiEvent.
Source Files