Skip to main content
Scripts

Umami Analytics

Copy for LLMs

Umami is an open-source web analytics platform that can run in Umami Cloud or on your own server.

Umami Analytics

View source

Nuxt Config Setup

Add this to your nuxt.config.ts to load Umami Analytics globally. Alternatively you can use the useScriptUmamiAnalytics composable for more control. 

export default defineNuxtConfig({
  scripts: {
    registry: {
      umamiAnalytics: {
        websiteId: '550e8400-e29b-41d4-a716-446655440000',
        trigger: 'onNuxtReady',
      }
    }
  }
})

This config automatically enables first-party mode (bundle + proxy). See below to customise.

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: Privacy Focused Proxy

No extra config needed. The script is bundled from your domain (faster loads, no extra DNS lookup) and runtime requests are reverse-proxied through your server with automatic anonymisation (user IPs stay hidden from Umami Analytics, works with ad blockers). Learn more.

Mode
Bundle Proxy Partytown
Privacy
User IP addresses are anonymised. Other request data passes through.
export default defineNuxtConfig({
  scripts: {
    // ✅ First-party mode: bundled + proxied
    registry: {
      umamiAnalytics: {
        websiteId: '550e8400-e29b-41d4-a716-446655440000',
        trigger: 'onNuxtReady',
      },
    },
  },
})

Example

Using Umami Analytics in a component with 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 use a self-hosted version of Umami, set hostUrl to your Umami origin. This maps to Umami's documented data-host-url setting and tells the tracker where to send events.

useScriptUmamiAnalytics({
  websiteId: 'YOUR_WEBSITE_ID',
  hostUrl: 'https://my-self-hosted'
})

Use scriptInput.src only if you also need to override the script URL itself.

Identify Sessions and Filter Data

Identify a Session

Umami's identify function accepts either a distinct ID or an object with session data:

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

// Set a distinct ID
proxy.identify('user-12345')

// Attach data to the session
proxy.identify({
  userId: 'user-12345',
  plan: 'premium'
})

Filter Data with beforeSend

Use beforeSend to inspect, modify, or cancel a payload before Umami receives it:

useScriptUmamiAnalytics({
  websiteId: 'YOUR_WEBSITE_ID',
  beforeSend: (type, payload) => {
    // Log what's being sent while 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'
})
websiteIdstring required

Your Umami website ID.

hostUrlstring

By default, Umami will send data to wherever the script is located. You can override this to send data to another location.

autoTrackboolean = true

By default, Umami tracks all pageviews and events for you automatically. You can disable this behavior and track events yourself using the tracker functions.

domainsstring[]

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.

tagstring

If you want the tracker to collect events under a specific tag. Events can be filtered in the dashboard by a specific tag.

beforeSendFunction | 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.

Edit this page
Markdown For LLMs

TikTok Pixel

Track TikTok conversions with consent, deduplication, and advanced matching.

Usercentrics

Load the Usercentrics CMP v3 and drive useScript consent triggers from UC_UI_CMP_EVENT events.