Usage

Functions

umTrackView()

Track page views.

Route changes are tracked automatically if autoTrack is enabled. If you're tracking manually, call the function onMounted;

type umTrackView = (
  url?: string | undefined, // optional
  referrer?: string | undefined // optional
) => Promise<{ ok: boolean }>;

Params

• url: the tracked path. Example: /about, /contact?by=phone#office. Optional, defaults to router.fullPath.
• referrer: the page referrer. Optional, defaults to document.referrer or the ref in searchParams (eg: example.com/?ref=website.com).

umTrackEvent()

Track custom events.

type DataValue = string | number | boolean;

type umTrackEvent = (
  name: string, // required
  data?: Record<string, DataValue> // optional
) => Promise<{ ok: boolean }>;

Params

• name: the event name. Required.
• data: the event data should be a {key: value} object, where key is a string and value is a string, number, or boolean.

umIdentify()

Tracks a session with dynamic data.

type DataValue = string | number | boolean;

type umIdentify = (
  data?: Record<string, DataValue> // optional
) => Promise<{ ok: boolean }>;

umTrackRevenue()

Collect revenue data.

type umTrackRevenue = (
  eventName: string, // required
  revenue: number, // required
  currency?: CurrencyCode, // optional, defaults to USD
) => Promise<{ ok: boolean }>;

type CurrencyCode = Uppercase<`${Letter}${Letter}${Letter}`>; // USD, EUR, NGN

Params

• eventName: the event name. Examples: cart-checkout, upgrade-checkout.
• revenue: amount to track. Examples: 24.99, 5000.
• currency: currency code, ISO 4217 standard.

Extra Props

Under the hood, umTrackRevenue is a convenient wrapper around umTrackEvent. If you need to add more data to your payload, you should consider extending umTrackEvent.

umTrackRevenue('premium-upgrade', 500, 'EUR');

// This is the same as

umTrackEvent('premium-upgrade', {
  revenue: 500,
  currency: 'EUR',
  ...otherData,
});
// must include `revenue` and `currency` to register as Umami revenue data

Return Value

All tracking functions return Promise<{ok: boolean}>.

The functions do not throw errors, use the ok status to check whether the request ran successfuly.
(During dev or if logErrors is set, errors are logged to the console.)

umTrackEvent().then(({ ok }) => console.log(ok));
// ...or
umTrackView().then(res => console.log(res.ok));

Directive

You can use umTrackEvent as a directive, v-umami. Add useDirective: true to your config.

v-umami requires a string as the event name, or an object containing a name property. Every other property will be passed on as event data.

<button v-umami="'Event-Name'">
  Event Button
</button>

<button v-umami="{name: 'Event-Name'}">
  as object
</button>

<button v-umami="{name: 'Event-Name', prop: 'value', ...others}">
  with event details
</button>