Tracking

Tracker configuration

Configure the Umami tracker with data attributes or window.umamiConfig for the host URL, auto-tracking, domains, tags, session salts, error tracking, performance, privacy, and a before-send hook.

The Umami tracker provides several properties that allow you to configure its behavior.

data-host-url#

v2.0.0

By default, Umami will send data to wherever the script is located. You can override this to send data to another location.

data-auto-track#

v2.0.0

By default, Umami initializes pageview tracking, click tracking, path change detection, and optional features like performance tracking. Set this to false only if you want to disable tracker initialization entirely and send data yourself using the tracker functions.

data-auto-pageview#

v3.2.0

Disable automatic pageview tracking while keeping the rest of the tracker initialized. Use this when you want to call umami.track() manually but still keep features like performance tracking enabled.

data-domains#

v2.0.0

If you want the tracker to only run on specific domains, you can add them to your tracker script. This is a comma-delimited list of domain names. Each value matches against window.location.hostname, so you should double-check if your website uses www or not. This helps if you are working in a staging/development environment.

data-tag#

v2.11.0

Group events under a named tag for filtering and A/B testing. See Tags for more details.

data-distinct-id#

v3.4.0

Set a Distinct ID for the visitor when the page loads. Every request the tracker sends, including the first pageview, carries the ID, so the visit is tied to the user from the start.

This is the recommended way to identify users whenever your page already knows who is logged in, for example when it is rendered on the server. Visitors on a shared network (an office, school, or VPN) can have the same IP address and browser, and Umami does not use cookies to tell them apart. Identifying them from the first pageview keeps each user's activity in their own session.

The value is read once, when the script loads. If a user logs in without a full page reload, call umami.identify() instead. The value is visible in your page's HTML, so use an internal user ID or a hash rather than an email address. It has a 50-character limit.

data-salt#

v3.5.0

A value mixed into the server's session salt. Visitors with different salts get different session IDs, so changing the value starts new sessions. For example, a salt of 2026-10-30 that you change every day rotates sessions daily.

The salt is only used when the server sets ENABLE_CLIENT_SALT. It adds to the server salt and never replaces it, so it can split sessions further but cannot merge them.

data-salt-rotation#

v3.5.0

Generates the salt from the current UTC time instead of a fixed value. Accepts hourly, daily, weekly, or monthly. Weeks start on Sunday. The salt is recalculated for every request, so a page that stays open still rotates. This setting is ignored when data-salt is set, and like data-salt it requires ENABLE_CLIENT_SALT on the server.

data-performance#

v3.1.0

Enable automatic collection of Core Web Vitals from your visitors' browsers. If you are sending pageviews manually, use data-auto-pageview="false" instead of data-auto-track="false" so performance tracking still initializes. See Performance for more details.

data-errors#

v3.5.0

Enable automatic capture of uncaught JavaScript exceptions and unhandled promise rejections from your visitors' browsers. This is also required for errors reported with umami.captureException(). See Error tracking for more details.

data-release#

v3.5.0

Attach a release or version to every captured error, so you can filter issues by release. It has a 100-character limit. Only used when data-errors is enabled.

data-environment#

v3.5.0

Attach an environment to every captured error, so you can filter issues by environment. Defaults to production and has a 50-character limit. Only used when data-errors is enabled.

v2.11.0

Use this if you don't want to collect search parameters from the URL.

data-exclude-hash#

v2.16.0

Use this if you don't want to collect the hash value from the URL.

data-do-not-track#

v2.17.0

Set this to true to disable Umami tracking when the browser exposes an enabled Do Not Track preference.

Do Not Track (DNT) is a deprecated browser feature with limited support, and its standardization has been discontinued. Umami retains this option for compatibility with browsers that expose the DNT preference.

This option only controls Umami's tracker behavior when that signal is available. It is not a comprehensive privacy or consent-management solution and does not prevent all HTTP requests or infrastructure logging.

data-before-send#

v2.18.0

Allows you to specify a function that will be called before data is sent. You can then inspect and modify the payload or cancel the send entirely. The function will take two parameters, type and payload. To continue with sending, you return a payload object. To cancel the send, return a falsy value. The handler must be a function on window that is defined before the tracker script loads.

When error tracking is enabled, the handler is also called for each captured error, with type set to error.

data-fetch-credentials#

v3.0.1

Sets the credentials mode for the requests the tracker sends. The default is omit. Use include if a proxy in front of your Umami collection endpoint needs cookies.

window.umamiConfig#

v3.5.0

Instead of data attributes, you can configure the tracker and the replay recorder with a window.umamiConfig object. Define it before the scripts load. Each key is the camelCase form of an attribute name without the data- prefix, so data-website-id becomes websiteId and data-exclude-search becomes excludeSearch.

A data attribute on the script tag always takes precedence over the same key in window.umamiConfig. That lets you share one configuration across pages and override individual settings where you need to.

  • Boolean values can be written as true or false rather than as strings.
  • domains accepts an array or a comma-separated string.
  • beforeSend accepts a function directly, or the name of a function on window, as data-before-send does. Other keys ignore function values.
  • With websiteId set in window.umamiConfig, the tracker also starts when it is loaded in a way that leaves document.currentScript empty, such as from a dynamically injected script or a bundle. In that case set hostUrl as well, because the tracker cannot infer the host from its own script URL.

The supported keys are websiteId, hostUrl, autoTrack, autoPageview, domains, tag, distinctId, salt, saltRotation, performance, errors, release, environment, excludeSearch, excludeHash, doNotTrack, beforeSend, and fetchCredentials. The recorder reads websiteId and hostUrl.