Umami
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
# 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
<!-- Add to your site's <head> -->
<script
defer
src="https://analytics.mysite.com/script.js"
data-website-id="your-website-id"
></script>
// 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
// 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
// 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-eventattribute — track clicks without JavaScriptumami.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