On this page
Before you add website analytics with Umami #
This walkthrough follows Umami Cloud's documented website setup. The sample site has three pages: /, /services/, and /contact/. Its contact link will send a named event, contact_link, so the traffic report and the contact action remain separate.
Choose a plan before starting. Hobby covers one website and 100,000 monthly events. If you already have a self-hosted account, the website and tracker steps are similar once the application is running. This guide doesn't install an application server.
Keep customer names, message text, email addresses, and other sensitive information out of event names and properties. A label describing an action is enough for this example.
1. Add the website to your account #
Open Websites in Umami's sidebar, then select Add website. Enter a recognizable Name, such as Studio website, and the site's Domain. Use the actual hostname the public website serves, then choose Save.
The official website instructions show these controls. When the save succeeds, the website appears in the account's website list. If you manage more than one domain, use names that make the destination obvious before copying any tracking code.
For the sample, the three pages belong to one website record. You don't need a separate record for /services/ or /contact/; the tracker associates their page paths with that website.
2. Copy the generated tracking code #
On the website record, open Edit, then Tracking code. Copy the script generated for that record. Its website identifier connects incoming activity with the website you just saved.
The collection documentation shows the tracker installation. Use the account-generated code as a whole. Don't borrow a website ID from an example or from another account record, because visits could arrive in the wrong report.
At this point you should have one script snippet for the sample site. Keep it in your site's shared tracking setting or layout so changes can be made in one place.
3. Install the script in the shared page head #
Put the copied snippet inside the site's <head>, using the website builder's head-code setting or the application's shared template. Publish that change through your normal website workflow.
For a three-page site, all three pages should inherit the same snippet. Adding it separately to a page and to the global template can cause duplicate collection. Search the rendered page source for the Umami script and check that it appears once.
The tracker configuration includes optional settings. Leave optional attributes out until you need them. If you use data-domains, its allowed hostnames must match the website you actually visit, including a www hostname when that is part of the setup.
4. Check that a page visit reaches the dashboard #
Visit the public home page in your browser, then open the website's Umami dashboard. Give collection a little time and look for incoming activity for the page. Repeat with /services/ and /contact/ so the example covers more than one path.
If no activity appears, use the browser's Network developer-tools panel to check whether the tracker loads and whether collection requests succeed. A failed script request points toward installation, network, or browser blocking. A successful script with no collection request calls for a closer look at configuration.
Don't use one blocked browser visit as the only installation check. Inspect the request and your site's published markup before changing the tracker. The Umami documentation on blocked trackers explains why a browser can stop the request.
5. Add a named contact-link event #
The event instructions document HTML attributes for click tracking. For a regular contact link, the sample can be written as:
<a href="/contact/" data-umami-event="contact_link">Contact the studio</a>Publish the change, follow the link, and check the dashboard for contact_link. The event says the link was clicked. It doesn't say an inquiry was sent, so keep the label specific to the action it measures.
Event names have a documented 50-character limit. Additional event properties need an event name. I'd start with the single label above and add properties only when they answer another question, such as distinguishing a header link from a footer link.
6. Read the sample as traffic plus one action #
Look at the pages in the website report and the named contact event. The metric definitions explain visitors, views, visits, and other report terms. Those labels aren't interchangeable.
The worked example answers two questions: which of the three pages people view, and whether they click the contact link. If the business later wants to count completed inquiries, add a separate event after a successful form submission. A click alone can't answer that question.
Before handing the report to someone else, write down the event name and its meaning in the website's own maintenance notes. That helps the next editor preserve the same measurement when changing the navigation.
Known problems and documented fixes #
Duplicate tracker initialization
Umami's version 3.1 announcement in April 2026 lists a fix for double tracker initialization. For a current installation, also check your markup for two copies of the script. A shared template and a tracking plugin can both insert it; keep one intentional installation.
An older login rejected an email's capitalization
A January 2026 Cloud issue reported case-sensitive email sign-in. It was closed after a fix, which is also listed in the version 3.1 release announcement. If an older setup shows that behavior, use the registered email spelling to regain access and update the self-hosted application through its documented upgrade route.
A configured hostname doesn't match the visited site
The tracker configuration makes domain filtering an exact-hostname setting. If the browser visits www.example.com while only example.com is allowed, correct the allowed domains. Confirm the final hostname after redirects before editing the setting.
Troubleshooting #
| Problem | Likely cause | What to check |
|---|---|---|
| No visits appear | Script wasn't published or its request is blocked | Published source and browser Network requests |
| Activity reaches the wrong website | Another record's website ID was copied | Generated Tracking code for this record |
| Counts look duplicated | Script inserted more than once | Shared template, plugin, and per-page code |
| Contact click has no event | Attribute missing from the actual link | Rendered data-umami-event attribute |
| One hostname has no traffic | Domain filter excludes it | data-domains and redirected hostname |
| Page paths differ from expectations | Site routing or redirects change the URL | Browser's final URL and collected paths |
Variations #
Use a single-page application
The SPA documentation says to load the tracker once in the root layout; it tracks navigation automatically. Don't add another pageview call on every component mount unless your documented tracking setup specifically requires it.
Separate header and footer contact links
Use the same event name with a documented property identifying placement. That lets the action remain one event while allowing a report to distinguish its position. Keep the property a short layout label; it doesn't need visitor information.
Use an existing self-hosted account
Use the tracking snippet generated by that installation, which points to its own collector. The website-record and event steps still apply. Let the application's documented deployment and backup process handle server maintenance separately from editing the website's script.
Completion checklist #
- The account has the intended website name and domain.
- The shared template inserts its generated tracker once.
- Visits to the home, services, and contact pages reach the report.
- The contact link sends
contact_link. - The event description matches a click, without implying a completed inquiry.
- No event name or property contains private visitor details.
Next steps #
Compare the reporting choices in Matomo vs Umami and the free website analytics shortlist. The Umami directory page and Umami alternatives cover other starting points. For a separate page-behavior question, see Microsoft Clarity.
