Tracking

Distinct IDs

Set a Distinct ID with umami.identify() or the Sending stats API to link a user's sessions and activity across visits and devices.

Available since v2.18.0

A Distinct ID is a unique identifier assigned to a user, either anonymously or when they log in. This allows you to associate actions (pageviews, clicks, conversions) with a single user across multiple sessions. For a more extensive way to identify a session, take a look at Session Data.

Use Cases#

  • Properly attribute user behavior.
  • Connect events across multiple sessions or devices.
  • Identify repeat users vs. new users.
  • Build out journeys and profiles based on user history.

Usage#

If your page already knows who the user is, for example because it is rendered on the server after login, add the data-distinct-id attribute to the tracker script:

The ID is sent with every request, starting with the first pageview, so the whole visit belongs to the user.

Shared networks

Umami does not use cookies, so it cannot tell apart visitors who share an IP address and browser, which is common on office, school, and VPN networks. Page views sent before a user is identified are anonymous, and on a shared network they can end up in a different session from the user's identified activity. Setting data-distinct-id avoids this, because the user is identified from the first request.

Set the ID after the page loads#

When the user logs in without a full page reload, as in a single-page app, set a Distinct ID with the umami.identify() tracker function by passing the ID as a string:

To set a Distinct ID and save session data at the same time, pass a data object as the second argument:

Alternatively, pass a single object with an id property. The id property sets the Distinct ID, and the object is saved as session data:

Send the ID with the API#

You can also set a Distinct ID by adding the id property to the event payload when using the Sending stats API directly:

The id property has a 50-character limit. If your identifiers are longer, consider using a hash or shortened version.

Session linking#

Setting a Distinct ID does not merge sessions together — each device/browser still gets its own session, identified independently by IP address, user agent, and website ID. Instead, Umami links each session to the Distinct ID.

When you open the profile for any session that has a Distinct ID, Umami automatically looks up every other session linked to that same ID and combines their activity into one timeline, expanding the visible date range to cover all of them. If a visitor is linked to more than one session, the profile shows a Linked IDs count so you know you're looking at combined, cross-device activity rather than a single visit.

Navigate to Sessions to view visitor activity.

Search for a specific Distinct ID to view all connected sessions for that time range.