Umami Analytics
Umami collects all the metrics you care about to help you make better decisions.
Script Stats
Nuxt Config Setup
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.
export default defineNuxtConfig({
scripts: {
registry: {
umamiAnalytics: {
websiteId: '550e8400-e29b-41d4-a716-446655440000'
}
}
}
})useScriptUmamiAnalytics
The useScriptUmamiAnalytics composable lets you have fine-grain control over when and how Umami Analytics is loaded on your site.
const { proxy } = useScriptUmamiAnalytics()
proxy.track('conversion', { value: 1 })Please follow the Registry Scripts guide to learn more about advanced usage.
First-Party Mode
This script supports First-Party Mode which routes all traffic through your domain for improved privacy and ad blocker bypass.
export default defineNuxtConfig({
scripts: {
firstParty: true,
registry: {
umamiAnalytics: { websiteId: '550e8400-e29b-41d4-a716-446655440000'}
}
}
})To opt-out for this specific script:
useScriptUmamiAnalytics({
websiteId: '550e8400-e29b-41d4-a716-446655440000',
scriptOptions: {
firstParty: false
}
})Example
Using Umami Analytics only in production while using the proxy to send events.
<script setup lang="ts">
const { proxy } = useScriptUmamiAnalytics()
// noop in development, ssr
// just works in production, client
function handleAction() {
proxy.track('conversion', { value: 1 })
}
</script>
<template>
<div>
<button @click="handleAction">
Send Event
</button>
</div>
</template>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> | string) => 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()),
/**
* Function that will be called before data is sent to Umami.
* The function takes two parameters: type and payload.
* Return the payload to continue sending, or return a falsy value to cancel.
*/
beforeSend: optional(union([
custom<(type: string, payload: Record<string, any>) => Record<string, any> | null | false>(input => typeof input === 'function'),
string(),
])),
})
Advanced Features
Session Identification
Umami v2.18.0+ supports setting unique session IDs using the identify function. You can pass either a string (unique ID) or an object with session data:
const { proxy } = useScriptUmamiAnalytics({
websiteId: 'YOUR_WEBSITE_ID'
})
// Using a unique string ID
proxy.identify('user-12345')
// Using session data object
proxy.identify({
userId: 'user-12345',
plan: 'premium'
})
Data Filtering with beforeSend
The beforeSend option allows you to inspect, modify, or cancel data before it's sent to Umami. This is useful for implementing custom privacy controls or data filtering:
useScriptUmamiAnalytics({
websiteId: 'YOUR_WEBSITE_ID',
beforeSend: (type, payload) => {
// Log what's being sent (for debugging)
console.log('Sending to Umami:', type, payload)
// Filter out sensitive data
if (payload.url && payload.url.includes('private')) {
return false // Cancel send
}
// Modify payload before sending
return {
...payload,
referrer: '' // Remove referrer for privacy
}
}
})
You can also provide a string with the name of a globally defined function:
// Define function globally
window.myBeforeSendHandler = (type, payload) => {
return checkPrivacyRules(payload) ? payload : false
}
useScriptUmamiAnalytics({
websiteId: 'YOUR_WEBSITE_ID',
beforeSend: 'myBeforeSendHandler'
})