Tracker functions

The Umami tracker exposes a function 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#

// Tracks the current page
umami.track();

// Custom payload
umami.track(payload: object);

// Custom event
umami.track(event_name: string);

// Custom event with data
umami.track(event_name: string, data: object);

// Assign ID to current session
umami.identify(unique_id: string);

// Session data
umami.identify(unique_id: string, data: object);

// Session data without ID
umami.identify(data: object);

Pageviews#

Track a page view.

umami.track();

By default the tracker automatically collects the following properties:

If you wish to send your own custom payload, pass in an object to the function:

umami.track({ website: 'e676c9b4-11e4-4ef1-a4d7-87001773e9f2', url: '/home', title: 'Home page' });

The above will only send the properties website, url and title. If you want to include existing properties, pass in a function:

umami.track(props => ({ ...props, url: '/home', title: 'Home page' }));

Events#

Track an event with a given name.

umami.track('signup-button');

Event Data#

Track an event with dynamic data.

umami.track('signup-button', { plan: 'newsletter', id: 123 });

When tracking events, the default properties are included in the payload. This is equivalent to running:

umami.track(props => ({
  ...props,
  name: 'signup-button',
  data: {
    plan: 'newsletter',
    id: 123,
  },
}));

Event Data Limits#

Event Data can work with any JSON data. There are a few rules in place to maintain performance.

Overriding Event Timestamps#

You can override the event timestamp by adding a UNIX timestamp in seconds to the payload:

umami.track(props => ({
  ...props,
  name: 'signup-button',
  timestamp: 1771523787, // new Date().getTime() / 1000
}));

Sessions#

Pass in your own ID to identify a user.

umami.identify('unique_id');

Session Data#

Save data about the current session.

umami.identify('unique_id', { name: 'Bob', email: 'bob@aol.com' });

To save data without a unique ID, pass in only a JSON object.

umami.identify({ name: 'Bob', email: 'bob@aol.com' });