Tracker configuration

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

data-host-url#

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

<script
  defer
  src="http://mywebsite.com/script.js"
  data-website-id="94db1cb1-74f4-4a40-ad6c-962362670409"
  data-host-url="http://stats.mywebsite.com"
></script>

data-auto-track#

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.

<script
  defer
  src="http://mywebsite.com/script.js"
  data-website-id="94db1cb1-74f4-4a40-ad6c-962362670409"
  data-auto-track="false"
></script>

data-auto-pageview#

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.

<script
  defer
  src="http://mywebsite.com/script.js"
  data-website-id="94db1cb1-74f4-4a40-ad6c-962362670409"
  data-auto-pageview="false"
></script>

data-domains#

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.

<script
  defer
  src="http://mywebsite.com/script.js"
  data-website-id="94db1cb1-74f4-4a40-ad6c-962362670409"
  data-domains="mywebsite.com,www.mywebsite.com"
></script>

data-tag#

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

<script
  defer
  src="http://mywebsite.com/script.js"
  data-website-id="94db1cb1-74f4-4a40-ad6c-962362670409"
  data-tag="homepage-layout-a"
></script>

data-distinct-id#

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.

<script
  defer
  src="http://mywebsite.com/script.js"
  data-website-id="94db1cb1-74f4-4a40-ad6c-962362670409"
  data-distinct-id="user-123"
></script>

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-performance#

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.

<script
  defer
  src="http://mywebsite.com/script.js"
  data-website-id="94db1cb1-74f4-4a40-ad6c-962362670409"
  data-performance="true"
></script>

data-exclude-search#

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

<script
  defer
  src="http://mywebsite.com/script.js"
  data-website-id="94db1cb1-74f4-4a40-ad6c-962362670409"
  data-exclude-search="true"
></script>

data-exclude-hash#

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

<script
  defer
  src="http://mywebsite.com/script.js"
  data-website-id="94db1cb1-74f4-4a40-ad6c-962362670409"
  data-exclude-hash="true"
></script>

data-do-not-track#

Respects the user's Do Not Track browser setting.

<script
  defer
  src="http://mywebsite.com/script.js"
  data-website-id="94db1cb1-74f4-4a40-ad6c-962362670409"
  data-do-not-track="true"
></script>

data-before-send#

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.

function beforeSendHandler(type, payload) {
  if (checkPayload(payload)) {
    return payload;
  }
  return false;
}

<script
  defer
  src="http://mywebsite.com/script.js"
  data-website-id="94db1cb1-74f4-4a40-ad6c-962362670409"
  data-before-send="beforeSendHandler"
></script>