idimsh 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 <head>; 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.umamisignatures, 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_caseevent 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:
<script
defer
src="https://your-umami.example.com/script.js"
data-website-id="YOUR-WEBSITE-UUID"
></script>
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-eventplusdata-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
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:
- Create
analyticshelpers such astrack(),identify(),trackAffiliateClick(),trackPromoViewOnce(), andtrackPurchase(). - Guard browser-only calls with
typeof window !== 'undefined'andwindow.umamichecks. - Use no-op or queue behavior so app logic does not break if the tracker is blocked or delayed.
- Keep event payloads flat, compact, and privacy-safe.
- Use JavaScript tracking for revenue and other numeric data.
- Use
data-before-sendto redact query strings, drop admin/internal pages, remove accidental PII, or normalize URLs. - For promotions, track both exposure and click (
promo_view,promo_click) so CTR can be computed. - For affiliate/outbound links, capture
destination_domain,placement,merchant/partner,campaign, andcta_idwhere available before navigation. - For funnels/goals/attribution, ensure each step has a stable URL or event name.
- 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
revenueand ISO 4217currency. data-before-sendredacts 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.