data-* attributes on the <script> tag itself — no separate configuration file or JavaScript initialisation call is needed. You add the attributes you need alongside data-website-id, and the tracker reads them as it loads. This keeps your setup declarative and easy to audit at a glance.
A fully-featured script tag might look like this:
Required
string
required
Your unique Betterumami website ID. Every request the tracker sends is tagged with this value so Betterumami knows which website the data belongs to. You can find this ID in the Tracking code section of your website’s edit panel.
Tracking Behaviour
boolean
default:"true"
Available since v2.0.0Controls whether the tracker initialises at all when the script loads. Set to
false only when you want to disable every form of automatic data collection — pageviews, click tracking, path change detection, and performance tracking — and send all data yourself using Tracker functions.boolean
default:"true"
Available since v3.2.0Disables automatic pageview tracking while leaving the rest of the tracker — including performance monitoring and click tracking — fully initialised. Use this when you want to fire pageviews manually via
umami.track() (for example, in a single-page application with a custom router) while still benefiting from automatic features.string
Available since v2.0.0A comma-separated list of hostnames on which the tracker is allowed to run. Each value is matched against
window.location.hostname. When data-domains is set, the tracker silently does nothing on any hostname not in the list — making it safe to deploy the same snippet across production, staging, and local development environments without polluting your production analytics.Be precise about whether your production site uses the
www subdomain. mywebsite.com and www.mywebsite.com are treated as different hostnames. Add both if your site is accessible at both addresses.Data Destination
string
Available since v2.0.0Overrides the URL that the tracker sends data to. By default, data is sent to the same origin as the script file. Use this attribute to route tracking requests to a different server — for example, a proxy you control, a self-hosted Betterumami instance, or a vanity domain that bypasses common ad-blocker block lists.
URL Collection
boolean
default:"false"
Available since v2.11.0Set to
true to strip query string parameters from every URL before it is recorded. Betterumami will store the path (e.g. /products) but not the query string (e.g. ?ref=newsletter&utm_source=email). Useful when query strings contain sensitive or high-cardinality values you don’t want appearing in your dashboard.boolean
default:"false"
Available since v2.16.0Set to
true to strip the hash fragment from every URL before it is recorded. Pages at /docs/intro#getting-started and /docs/intro#installation will both be recorded as /docs/intro. Helpful when your hash fragments reflect in-page anchor links that you don’t want counted as separate pages.Privacy
boolean
default:"false"
Available since v2.17.0Set to
true to honour the browser’s Do Not Track setting. When a visitor has DNT enabled and this attribute is set, the tracker will not send any data for that visitor.string
Available since v2.18.0The name of a JavaScript function (defined in the global scope) that is called before every tracking request is sent. The function receives two arguments —
type and payload — and must return either a (possibly modified) payload object to allow the send, or a falsy value to cancel it entirely. Use this for last-mile filtering, payload enrichment, or conditional suppression of specific events.Define the handler before the script tag
The handler function must be defined in the global scope (
window.beforeSendHandler) before the Betterumami script executes. Define it in a <script> block that appears earlier in the <head> than the Betterumami <script> tag.Performance & Experiments
boolean
default:"false"
Available since v3.1.0Set to
true to automatically collect Core Web Vitals — LCP, INP, CLS, FCP, and TTFB — from your visitors’ browsers. Results appear in the Performance section of your dashboard.string
Available since v2.11.0Tags every event sent by this script instance with a named label. Use tags to separate traffic from different experiments, page variants, or deployment cohorts and then filter your dashboard by tag.