Tracker functions
Use the umami.track(), umami.identify(), and umami.captureException() tracker functions to send pageviews, events, event data, session data, and errors from your own code.
The Umami tracker exposes functions that you can call on your website if you want
more control over your tracking. By default everything is automatically collected, but you can
disable automatic pageviews using data-auto-pageview="false" and send them yourself with umami.track().
Use data-auto-track="false" only if you want to disable tracker initialization entirely.
See Tracker configuration.
Functions#
v2.0.0Pageviews#
v2.0.0Track a pageview.
By default the tracker automatically collects the following properties:
| Property | Description |
|---|---|
hostname | Hostname of server |
language | Browser language |
referrer | Page referrer |
screen | Screen dimensions (e.g. 1920x1080) |
title | Page title |
url | Page URL |
website | Website ID (required) |
If you wish to send your own custom payload, pass in an object to the function:
The above will only send the properties website, url and title. If you want to include existing properties, pass in a function:
Events#
v2.0.0Track an event with a given name.
Event Data#
v2.0.0Track an event with dynamic data.
When tracking events, the default properties are included in the payload. This is equivalent to running:
Event Data Limits#
Event data can work with any JSON data. There are a few rules in place to maintain performance.
| Data Type | Limit |
|---|---|
| Numbers | Max precision of 4. |
| Strings | Max length of 500. |
| Arrays | Converted to a string, max length of 500. |
| Objects | Max of 50 properties. Arrays are considered 1 property. |
Overriding Event Timestamps#
You can override the event timestamp by adding a Unix timestamp in seconds to the payload:
Sessions#
v2.13.0Pass in your own ID to identify a user.
If the user is already known when the page loads, set the ID with the
data-distinct-id attribute instead, so the first pageview is
identified too. See Distinct IDs.
Session Data#
v2.13.0Save data about the current session.
To save data without a unique ID, pass in only a JSON object.
If the object includes an id property, its value is also used as the Distinct ID.
Errors#
v3.5.0Report an error that your code has caught. Requires data-errors.
Pass an optional second argument to add a release, environment, tags, or a fingerprint. See
Error tracking for details.