# Umami Analytics Web > agent-friendly implementation guidance for Umami Analytics v3 in web projects. Use when building, reviewing, or configuring privacy-first website analytics with Umami, including tracker setup, custom events, CTAs, affiliate/outbound links, downloads, forms, promotions, revenue, UTM campaigns, pixels, links, goals, funnels, journeys, attribution, tags, distinct IDs, server-side events, and GA4-style migration or concept comparisons. - Skill: `idimsh/umami-analytics-web` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add idimsh/umami-analytics-web` - Raw SKILL.md: https://api.skillmd.com/api/skills/idimsh/umami-analytics-web/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Data & Analytics - Author: idimsh (https://skillmd.com/u/idimsh) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/idimsh/umami-analytics-web --- # Umami Analytics Web Use this skill to help a coding agent implement or review Umami Analytics in websites, landing pages, ecommerce flows, marketing campaigns, newsletters, embedded content, or privacy-first analytics setups. Umami v3 is an open-source, cookieless, privacy-first web analytics platform. A website normally embeds one small tracker script in ``; pageviews are auto-collected, and custom events are recorded with either HTML `data-*` attributes or `window.umami.track()`. ## Load the right reference - `references/recipes.md` — start here for most implementation tasks: CTAs, outbound/affiliate links, downloads, forms, promotions, checkout/revenue, distinct IDs, A/B tags, SPA patterns, consent-friendly wrappers, and QA. - `references/event-taxonomy.md` — use before adding new events so names, properties, PII rules, and funnel/revenue events stay consistent. - `references/tracker-reference.md` — use for tracker script attributes, `window.umami` signatures, default payloads, SPA behavior, `data-before-send`, server-side ingestion, ad-blocker bypass, and replay options. - `references/pixels-and-links.md` — use for Umami Pixel and Link concepts, email-open/image-pixel tracking, tracked redirect links, QR/social/ad/off-site campaigns, and when to combine them. - `references/features-and-ga4-comparison.md` — use when asked what Umami offers, how it compares to GA4, or how to translate a GA4 concept into Umami. ## Operating principles - Prefer privacy-first analytics: avoid cookies, fingerprinting, raw PII, secrets, raw user-generated content, and full sensitive URL query strings. - Treat `data-website-id`, tracker URL, and Umami host as deployment configuration. - Add an analytics wrapper module instead of scattering raw `umami.track()` calls across components. - Track events that answer a decision: conversion, product usage, campaign, affiliate/revenue, UX, content, or funnel analysis. - Keep event names stable and put context in properties. Do not create one event name per button, page variant, product, coupon, or campaign. - Default to `lower_snake_case` event names and property names in new code. If a project already uses kebab/camel case, preserve consistency rather than mixing styles. - For GA4 migrations, map GA4 event intent to Umami events/goals/funnels/revenue/attribution; do not blindly copy the full GA4 ecommerce schema unless the business needs item-level detail outside Umami. ## Install the tracker Place this once in the global document head/layout: ```html ``` Common configuration attributes: | Attribute | Use | | --- | --- | | `data-website-id` | Required website UUID from Umami. | | `data-host-url` | Send beacons to a different host than the script origin. | | `data-auto-track="false"` | Disable automatic pageviews/events so code calls `umami.track()` manually. | | `data-domains="example.com,www.example.com"` | Restrict tracking to production hostnames or known domains. | | `data-tag="variant-a"` | Stamp every event with an A/B variant, release cohort, microsite, or campaign tag. | | `data-performance="true"` | Collect Core Web Vitals/performance metrics. | | `data-exclude-search="true"` | Strip URL query strings from collected URLs. | | `data-exclude-hash="true"` | Strip URL hash fragments from collected URLs. | | `data-do-not-track="true"` | Respect the browser Do Not Track setting. | | `data-before-send="fnName"` | Globally inspect, redact, enrich, or reject outgoing payloads. | ## Choose the correct tracking method - Static click in rendered HTML: use `data-umami-event` plus `data-umami-event-*` attributes. - Dynamic values, typed numbers/booleans/dates, revenue, delayed callbacks, SPA/framework handlers: use `window.umami.track(name, data)` through a wrapper. - Session annotation or privacy-safe user stitching: use `window.umami.identify()` with a hashed/opaque ID or session properties. - Backend events, webhooks, jobs, or mobile/API activity: use Umami server-side ingestion or a client library described in `tracker-reference.md`. - Email opens, RSS, partner embeds, or no-JavaScript contexts: use Umami Pixel. - Shareable off-site campaign URLs, social bios, paid ads, QR codes, podcast notes, SMS, or affiliate redirects: use Umami Link. ## Event API quick reference ```js umami.track(); // pageview for current page umami.track('event_name'); // custom event umami.track('event_name', { foo: 1 }); // custom event with data umami.track(payload); // custom payload, replaces defaults umami.track(props => ({ ...props, url: '/x' })); // merge into default payload umami.identify('opaque_user_id'); // assign distinct ID umami.identify('opaque_user_id', { plan: 'pro' }); umami.identify({ plan: 'pro' }); // session properties only ``` Event constraints to respect: - Event names: 50 characters or less. - Data attributes send event property values as strings. - JavaScript tracking preserves types and is preferred for revenue/numeric analysis. - Event data strings should stay 500 characters or less; numbers have max precision of 4; objects should stay at 50 properties or fewer; arrays are serialized to strings. ## Coding-agent requirements When adding Umami to code: 1. Create `analytics` helpers such as `track()`, `identify()`, `trackAffiliateClick()`, `trackPromoViewOnce()`, and `trackPurchase()`. 2. Guard browser-only calls with `typeof window !== 'undefined'` and `window.umami` checks. 3. Use no-op or queue behavior so app logic does not break if the tracker is blocked or delayed. 4. Keep event payloads flat, compact, and privacy-safe. 5. Use JavaScript tracking for revenue and other numeric data. 6. Use `data-before-send` to redact query strings, drop admin/internal pages, remove accidental PII, or normalize URLs. 7. For promotions, track both exposure and click (`promo_view`, `promo_click`) so CTR can be computed. 8. For affiliate/outbound links, capture `destination_domain`, `placement`, `merchant`/`partner`, `campaign`, and `cta_id` where available before navigation. 9. For funnels/goals/attribution, ensure each step has a stable URL or event name. 10. Validate in Umami Events/Properties, then create Goals, Funnels, Journey, Revenue, Attribution, or UTM views from the collected events. ## Recommended default events Use these unless the project already has a taxonomy: | Event | Use | | --- | --- | | `cta_click` | Major CTA click. | | `affiliate_click` | Click to partner/merchant/affiliate destination. | | `outbound_click` | Non-affiliate external link. | | `promo_view` | Promotion/banner/offer becomes visible. | | `promo_click` | Promotion/banner/offer is clicked. | | `promo_apply` | Coupon/offer is applied. | | `lead_submit` | Lead/demo/contact form submitted successfully. | | `signup_start` / `signup_complete` | Signup funnel. | | `checkout_start` / `checkout_complete` / `purchase` | Checkout and revenue funnel. | | `search` | Site search performed. | | `download` | File/resource download. | | `video_play` | Video engagement starts. | ## Common pitfalls to prevent - Do not duplicate SPA pageviews: Umami already listens to History API in normal SPAs. - Do not send raw email addresses or full user IDs; use opaque IDs or hashes and keep distinct IDs within Umami's limit. - Do not rely on data attributes when numeric aggregation matters; use JavaScript. - Do not include secrets or personal data in `url`, event names, or properties. - Do not mix Umami Links with in-site click events unless both the redirect and the on-site interaction are intentionally needed. - Do not assume email pixel opens are exact human opens; image proxying and prefetching can inflate pixel metrics. - Do not treat Umami as a one-for-one GA4 replacement for Google Ads optimization, BigQuery pipelines, app+web, predictive audiences, or detailed item-level ecommerce reporting. ## QA checklist Before finishing an implementation, verify: - Tracker script loads once in production and pageviews appear. - Staging/dev traffic is excluded with `data-domains`, separate websites, or environment gates. - Event names follow one convention and are 50 characters or less. - Properties are visible and filterable in Umami Events > Properties. - Revenue events use numeric `revenue` and ISO 4217 `currency`. - `data-before-send` redacts or rejects unsafe payloads. - Goals/funnels use stable events/pages and meaningful conversion steps. - UTM parameters are preserved unless deliberately excluded. - Links/Pixels are used only where redirect/pixel semantics fit the channel.