Umami analytics web

Skill idimsh/tdds-frontend-skills/umami-analytics-web

Frontend AI agent skills (SKILL.md) for UI pre-delivery checks, accessibility audits, and fixing patterns across Next.js, React, and other web projects

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.

What its author says it does

Copied from the file, not written here

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

9.0 KB, 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.