Umami Analytics

Umami collects all the metrics you care about to help you make better decisions.

The simplest way to load Umami Analytics globally in your Nuxt App is to use Nuxt config. Alternatively you can directly use the useScriptUmamiAnalytics composable.

Loading Globally

If you don't plan to send custom events you can use the Environment overrides to disable the script in development.

export default defineNuxtConfig({
  scripts: {
    registry: {
      umamiAnalytics: {
        websiteId: 'YOUR_WEBSITE_ID'
      }
    }
  }
})

useScriptUmamiAnalytics

The useScriptUmamiAnalytics composable lets you have fine-grain control over when and how Umami Analytics is loaded on your site.

const umami = useScriptUmamiAnalytics({
  websiteId: 'YOUR_WEBSITE_ID'
})

Please follow the Registry Scripts guide to learn more about advanced usage.

Self-hosted Umami

If you are using a self-hosted version of Umami, you will need to provide an explicit src for the script so that the API events are sent to the correct endpoint.

useScriptUmamiAnalytics({
  scriptInput: {
    src: 'https://my-self-hosted/script.js'
  }
})

UmamiAnalyticsApi

export interface UmamiAnalyticsApi {
  track: ((payload?: Record<string, any>) => void) &((event_name: string, event_data: Record<string, any>) => void)
  identify: (session_data?: Record<string, any>) => void
}

Config Schema

You must provide the options when setting up the script for the first time.

export const UmamiAnalyticsOptions = object({
  websiteId: string(), // required
  /**
   * By default, Umami will send data to wherever the script is located.
   * You can override this to send data to another location.
   */
  hostUrl: optional(string()),
  /**
   * By default, Umami tracks all pageviews and events for you automatically.
   * You can disable this behavior and track events yourself using the tracker functions.
   * https://umami.is/docs/tracker-functions
   */
  autoTrack: optional(boolean()),
  /**
   * 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.
   * Helps if you are working in a staging/development environment.
   */
  domains: optional(array(string())),
  /**
   * If you want the tracker to collect events under a specific tag.
   * Events can be filtered in the dashboard by a specific tag.
   */
  tag: optional(string()),
})

Example

Using Umami Analytics only in production while using track to send a conversion event.

<script setup lang="ts">
const { track } = useScriptUmamiAnalytics()

// noop in development, ssr
// just works in production, client
track('event', { name: 'conversion-step' })

function sendConversion() {
  track('event', { name: 'conversion' })
}
</script>

<template>
  <div>
    <button @click="sendConversion">
      Send Conversion
    </button>
  </div>
</template>