Umami analytics web

Skill idimsh/tdds-frontend-skills/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.From its SKILL.md

Install

npx -y skills add idimsh/tdds-frontend-skills --skill umami-analytics-web

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

9.0 KB, ~2.0k tokens by cl100k_base, as published. Nobody here has run it

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.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:

<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-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

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 analytics helpers such as track(), identify(), trackAffiliateClick(), trackPromoViewOnce(), and trackPurchase().
Guard browser-only calls with typeof window !== 'undefined' and window.umami checks.
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-send to 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, and cta_id where 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 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.