Umami

Umami

Expert at deploying and managing Umami, a privacy-focused open-source web analytics platform.

Overview

• Self-hosted analytics — GDPR-compliant, no cookies, lightweight tracker (~2KB)
• API Client — @umami/api-client TypeScript package for all API endpoints
• Node Client — @umami/node for server-side event tracking
• Tracker — Client-side umami.track() and umami.identify() functions
• Reports — Attribution, funnel, retention, journey, revenue, and UTM analysis
• Realtime — Live visitor data with 30-minute rolling window

CLI Tool (umami-cli)

A Rust CLI for managing self-hosted Umami instances from the terminal. Covers auth, websites, stats, events, sessions, reports, realtime, teams, users, admin, shares, links, and pixels.

• GitHub: https://github.com/zot24/umami-cli
• Language: Rust (requires cargo)

Install globally

# From source (clone first)
cargo install --path .

# Or directly from GitHub
cargo install --git https://github.com/zot24/umami-cli.git

After install, umami-cli is available globally via ~/.cargo/bin/.

CLI subcommands

umami-cli auth       # Login, logout, verify
umami-cli websites   # Manage websites
umami-cli stats      # View website statistics
umami-cli events     # Manage and track events
umami-cli sessions   # View session data
umami-cli reports    # Run and manage reports
umami-cli realtime   # View realtime analytics
umami-cli teams      # Manage teams
umami-cli users      # User management
umami-cli admin      # Admin operations (self-hosted only)
umami-cli shares     # Manage share pages
umami-cli links      # Manage tracked links
umami-cli pixels     # Manage tracking pixels

Quick Start

# Docker Compose (recommended for the Umami server)
git clone https://github.com/umami-software/umami.git
cd umami
docker-compose up -d
# Access at http://localhost:3000 (admin/umami)

// API Client
import { getClient } from '@umami/api-client';
const client = getClient();
const { ok, data } = await client.getWebsites();

Core Concepts

Authentication — Self-hosted uses POST /api/auth/login for bearer tokens. Cloud uses API keys. The API client handles auth via environment variables.

Tracking — Add <script src="/script.js" data-website-id="..."> to pages. Use umami.track() for pageviews and custom events, umami.identify() for session data.

API Client Config — Set UMAMI_API_CLIENT_USER_ID, UMAMI_API_CLIENT_SECRET, and UMAMI_API_CLIENT_ENDPOINT for self-hosted. Set UMAMI_API_KEY and UMAMI_API_CLIENT_ENDPOINT for Cloud.

Documentation Index

Setup & Configuration

• Installation — Docker, source, and cloud setup
• Environment Variables — Full configuration reference
• Authentication — Login, tokens, API keys

Client Libraries

• API Client — @umami/api-client TypeScript client with all methods
• Node Client — @umami/node server-side tracking

Tracking & Events

• Tracker Functions — Client-side umami.track() and umami.identify()
• Event Taxonomy ��� Naming conventions, categories, central registry pattern
• Auto-Enrichment — Enhanced trackEvent with auto device/geo context
• Implementation Patterns — Forms, CTAs, sections, funnels, privacy, Next.js
• Sending Stats — Direct POST /api/send (no auth required)

Analytics & Optimization

• Funnel Design — B2C, B2B, SaaS, e-commerce, onboarding funnel templates with benchmarks
• Journey Analysis — User journey archetypes, geographic/language variations, multi-visit patterns

API Reference

• Websites API — Website CRUD operations
• Website Statistics — Metrics, pageviews, active users
• Events API — Event tracking and data retrieval
• Sessions API — Session data and activity
• Reports API — Attribution, funnel, retention, journey, revenue, UTM
• Realtime API — Live visitor data (30-min window)
• Teams & Users — Team, user, and me endpoints
• Admin API — Admin-only endpoints (self-hosted)
• Share API — Share page management
• Links & Pixels — URL shortening and tracking pixels

Common Workflows

Get website stats for last 7 days

const client = getClient();
const now = Date.now();
const weekAgo = now - 7 * 24 * 60 * 60 * 1000;
const { data } = await client.getWebsiteStats('website-id', {
  startAt: weekAgo, endAt: now
});

Track custom event from server

import umami from '@umami/node';
umami.init({ websiteId: 'your-id', hostUrl: 'https://your-umami.com' });
umami.track({ url: '/api/checkout', name: 'purchase', data: { amount: 99 } });

Create a funnel report

const { data } = await client.createReport({
  websiteId: 'id', type: 'funnel',
  parameters: { startDate: '...', endDate: '...', urls: ['/signup', '/onboard', '/activate'] }
});

Upstream Sources

• Website: https://umami.is
• Documentation: https://docs.umami.is
• GitHub: https://github.com/umami-software/umami
• API Client: https://www.npmjs.com/package/@umami/api-client
• Node Client: https://www.npmjs.com/package/@umami/node

Sync & Update

When user runs sync: fetch latest from upstream, update docs/. When user runs diff: compare current vs upstream, report changes.