Overview

Umami is a privacy-focused web analytics platform — tracks page views, visitors, and custom events without cookies or personal data collection. GDPR/CCPA compliant by default (no consent banner needed). Self-hostable on your own infrastructure, or use Umami Cloud. Clean dashboard, real-time stats, and an API for programmatic access. The #1 open-source Google Analytics alternative.

When to Use

Need website analytics without cookie consent banners
GDPR/CCPA compliance is mandatory
Don't trust Google with your analytics data
Want to self-host analytics on your infrastructure
Simple, clean analytics without the complexity of GA4
API access to analytics data for dashboards/reporting

Instructions

Self-Host Setup

bash

# Docker Compose
git clone https://github.com/umami-software/umami.git
cd umami
docker compose up -d

# Or one-click deploy to Vercel/Netlify/Railway
# See: https://umami.is/docs/install

Add Tracking Script

html

<!-- Add to your site's <head> -->
<script
  defer
  src="https://analytics.mysite.com/script.js"
  data-website-id="your-website-id"
></script>

tsx

// Next.js — app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script
          defer
          src="https://analytics.mysite.com/script.js"
          data-website-id="your-website-id"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

Custom Event Tracking

typescript

// Track custom events
// Umami exposes a global `umami` object

// Track button clicks
document.getElementById("signup-btn")?.addEventListener("click", () => {
  umami.track("signup-click", { plan: "pro", source: "header" });
});

// Track form submissions
function handleSubmit(formData: FormData) {
  umami.track("form-submit", {
    form: "contact",
    subject: formData.get("subject"),
  });
}

// Track with React
function PricingCard({ plan }: { plan: string }) {
  return (
    <button
      onClick={() => umami.track("pricing-click", { plan })}
      data-umami-event="pricing-click"
      data-umami-event-plan={plan}
    >
      Choose {plan}
    </button>
  );
}

API Access

typescript

// api/analytics.ts — Fetch analytics data programmatically
const UMAMI_URL = "https://analytics.mysite.com";
const UMAMI_TOKEN = process.env.UMAMI_API_TOKEN;

async function getPageViews(websiteId: string, days = 30) {
  const endDate = Date.now();
  const startDate = endDate - days * 24 * 60 * 60 * 1000;

  const res = await fetch(
    `${UMAMI_URL}/api/websites/${websiteId}/pageviews?startAt=${startDate}&endAt=${endDate}&unit=day`,
    { headers: { Authorization: `Bearer ${UMAMI_TOKEN}` } }
  );
  return res.json();
}

async function getTopPages(websiteId: string) {
  const endDate = Date.now();
  const startDate = endDate - 7 * 24 * 60 * 60 * 1000;

  const res = await fetch(
    `${UMAMI_URL}/api/websites/${websiteId}/metrics?startAt=${startDate}&endAt=${endDate}&type=url`,
    { headers: { Authorization: `Bearer ${UMAMI_TOKEN}` } }
  );
  return res.json();  // [{ x: "/pricing", y: 1234 }, ...]
}

Examples

Example 1: Add privacy-friendly analytics to a SaaS

User prompt: "Add analytics to our SaaS without cookies or consent banners."

The agent will deploy Umami, add the tracking script, set up custom events for key actions (signup, upgrade, feature use), and create an API integration for internal dashboards.

Example 2: Build a custom analytics dashboard

User prompt: "Pull our Umami data into a custom dashboard for the marketing team."

The agent will use the Umami API to fetch page views, top pages, referrers, and events, then display them in a React dashboard.

Guidelines

No cookies = no consent banner — GDPR compliant by default
data-umami-event attribute — track clicks without JavaScript
umami.track(name, data) for custom events — flexible event tracking
Self-host for full control — Docker, Vercel, Railway, or any Node.js host
API for programmatic access — build custom dashboards and reports
Multi-site support — one Umami instance tracks multiple websites
Real-time dashboard — see active visitors now
UTM tracking — campaign attribution works automatically
Lightweight script — <2KB, doesn't slow down your site
PostgreSQL or MySQL — your choice for the backend database

umami

Usage

Getting Started

Example Prompts

Documentation