Umami Analytics Integration Plugin

Umami Analytics is a web analytics platform available as a managed Cloud service or a self-hosted open-source installation. Its standard tracker works without cookies, cross-site tracking, or the automatic collection of personal data.

The Umami Analytics Integration plugin connects a Publii site to Umami without requiring changes to the theme. It supports current Umami tracker options, optional Core Web Vitals collection, domain and URL controls, Preview Mode, and Publii's built-in Cookie Banner.

Requirements

Publii 0.45 or newer.
An Umami Cloud account or a working self-hosted Umami installation.
A Website ID and tracker script URL copied from the tracking code for your website in Umami.
An existing Publii Cookie Group if you enable Cookie Banner integration.

The plugin is free. Umami Cloud is a managed service, while the open-source edition runs on your own infrastructure. Review the current Umami plans and the self-hosting requirements before choosing a setup.

Installing the plugin

Open Publii's App Menu using the three-dot icon in the top-right corner.
Select Plugins.
Click Get More Plugins to open the Publii Plugin Marketplace.
Open the Umami Analytics plugin page and download the installation package.
Return to the Plugins screen in Publii and click Install Plugin.
Select the downloaded ZIP file. Do not extract it before installation.

Finding the Website ID and tracker script URL

Sign in to Umami.
Open the website you want to connect and edit its settings.
Find the Tracking code section.
Copy the value of data-website-id. It resembles 94db1cb1-74f4-4a40-ad6c-962362670409.
Copy the complete address from the script's src attribute. Umami Cloud normally uses https://cloud.umami.is/script.js. A self-hosted installation uses the address shown by that installation.

Enter the identifier in Website ID and the script address in Tracker script URL. Copy these two values rather than pasting the complete script element. See Umami's Collect data guide for the current location of the tracking code.

Activating the plugin

Open Tools & Plugins in Publii.
Find Umami Analytics Integration and enable its switch.
Click the plugin card to open its options.
Enter the Website ID and tracker script URL.
Review the tracking, privacy, and consent settings, then save the changes.
Regenerate and publish the website.

The plugin does not generate tracking code when a required value or an enabled Cookie Banner setting is missing or invalid.

Umami Analytics plugin options

Configuration

Website ID – The unique UUID assigned to the website in Umami. This field is required. Copy only the value of data-website-id from the Umami tracking code.
Tracker script URL – The address from the src attribute of the Umami tracking code. This field is required. It accepts a complete HTTP or HTTPS URL, such as https://cloud.umami.is/script.js, or a root-relative proxy path, such as /stats/script.js. Protocol-relative addresses beginning with //, credentials, and URL fragments are not accepted.
Custom data host URL – An optional base URL that tells the tracker to send data somewhere other than the script's location. Leave it empty for a standard Umami Cloud or self-hosted setup. Use it when a reverse proxy, CDN, or custom deployment serves the script and collection endpoint from different addresses. Enter a complete HTTP or HTTPS base URL without credentials, a query string, or a fragment.
Output code in Preview Mode – Includes the tracker in pages opened through Publii Preview. The option is disabled by default because preview visits can enter analytics reports. Enable it temporarily when inspecting generated code or network requests.

Tracking options

Initialize automatic tracking – Lets Umami initialize automatic page views, path-change tracking, click events, and optional performance tracking. It is enabled by default. When disabled, the tracker loads with automatic initialization turned off and data must be sent through Umami's tracker functions. Disabling this setting also prevents the plugin's Core Web Vitals option from taking effect.
Track page views automatically – Records page views automatically while leaving the rest of the tracker active. Disable it when you want to send page views manually through umami.track() but still need click, navigation, or performance tracking. This option requires Umami 3.2 or newer and appears only while automatic tracking is enabled.
Track Core Web Vitals – Enables real-user performance collection in Umami. It records LCP, INP, CLS, FCP, TTFB, and page duration. This option requires Umami 3.1 or newer and appears only while automatic tracking is enabled.
Respect the browser's Do Not Track setting – Tells Umami not to track a visitor when the browser sends a Do Not Track preference. It is enabled by default. Umami added this tracker option in version 2.17.

Privacy and data controls

Exclude URL search parameters – Removes the query string from page URLs and referrers before Umami sends them. This can reduce duplicate page addresses and prevent unintended values in a query string from reaching analytics. Umami added this option in version 2.11.
Exclude URL fragments – Removes the hash fragment from page URLs and referrers before Umami sends them. Umami added this option in version 2.16.
Allowed domains – Limits the tracker to a comma-separated list of exact hostnames. Enter values such as example.com,www.example.com. Do not include a protocol, path, port, or wildcard. Include both the root domain and its www version when the site uses both. Leave the field empty to let the tracker run wherever the generated site is published.

Advanced options

Tracking tag – Adds a tag to events so they can be grouped and filtered in Umami. Tags can also support experiments that compare data collected under different labels. Umami added tracker tags in version 2.11.
Before-send function – Names a global JavaScript function that Umami calls before sending a page view or event. The function can inspect or change the payload, or cancel the request by returning a false value. Enter only the function name, such as beforeSendHandler. The function must already exist when the tracker starts. Umami added this option in version 2.18.

The before-send option is intended for developers. A function that returns an invalid value or throws an error can prevent analytics data from being sent. See Umami's before-send documentation before enabling it.

Cookie Banner integration

Require consent before loading – Connects the tracker to Publii's built-in Cookie Banner. When enabled, Publii blocks the complete Umami script and all Umami requests until the visitor accepts the selected Cookie Group.
Cookie Group ID – The internal ID of an existing group under Site Settings → Privacy Settings → Cookie Groups. The option appears after consent blocking is enabled. An Analytics group with the ID analytics is suitable for many sites.

Choosing automatic or manual tracking

Keep Initialize automatic tracking and Track page views automatically enabled for a standard Publii site. Umami records page loads automatically, and no additional tracking code is required.

If you want to send page views manually but keep the tracker initialized, leave Initialize automatic tracking enabled and disable Track page views automatically. You can then call umami.track() from your own JavaScript. This combination requires Umami 3.2 or newer and allows Core Web Vitals tracking to remain active.

Disable Initialize automatic tracking only when your own code will control the complete Umami tracker lifecycle. This setting disables automatic page views, click tracking, path-change detection, and performance initialization. Read the Umami tracker functions documentation before using this mode.

Tracking Core Web Vitals

Enable Track Core Web Vitals to collect performance measurements from real visits. Umami 3.1 or newer is required. The tracker can report Largest Contentful Paint, Interaction to Next Paint, Cumulative Layout Shift, First Contentful Paint, Time to First Byte, and page duration.

Performance tracking requires the tracker to initialize. If you send page views manually, disable only Track page views automatically. Do not disable Initialize automatic tracking, because the plugin will not add the performance setting in that mode.

Using a proxy or separate collection address

Most installations need only the tracker script address supplied by Umami. The tracker sends data to the same Umami location by default.

If a reverse proxy exposes the tracker under the Publii site's own domain, enter its root-relative path in Tracker script URL, for example /stats/script.js. Query strings are supported when the proxy requires one. Do not enter a protocol-relative address beginning with //.

Use Custom data host URL only when the collection endpoint has a different base address from the script. For example, a script served through a CDN may send data to the original Umami server. Confirm the required value in the tracking code or deployment instructions for your Umami installation.

Limiting tracking to selected domains

Use Allowed domains when the same generated files may appear on production, staging, or development hosts and only selected hosts should send analytics. Umami compares each entry with the browser's current hostname.

Enter exact hostnames separated by commas. The plugin removes duplicate entries and normalizes them to lowercase. Wildcards are not supported, so *.example.com is invalid. If both example.com and www.example.com serve the website, list both values.

An incomplete list can stop tracking on a valid production hostname. After changing this setting, test every public hostname used by the website.

Configuring the Publii Cookie Banner

Umami's standard tracker does not use cookies. Cookie-free analytics can still involve requests and data collection, so your privacy policy, tracker configuration, visitors, and applicable rules determine whether prior consent is required. Publii's Cookie Banner integration is available when you need to block Umami until consent.

Open Site Settings → Privacy Settings.
Enable the Cookie Banner and its advanced cookie configuration.
Create or review the group used for analytics consent.
Set a Group ID, such as analytics. Use letters, numbers, hyphens, or underscores without spaces. The first character must be a letter or number.
Open the Umami plugin and enable Require consent before loading.
Enter the exact same value in Cookie Group ID.
Save the settings, regenerate the website, and test the banner.

When the integration is active, Publii prevents the tracker script from loading before the selected group is accepted. This blocks page views, events, Core Web Vitals, and other requests generated by that tracker. If the Cookie Banner, advanced configuration, selected group, or Group ID is missing, the plugin outputs no Umami tracking code.

Read the Publii Cookie Banner documentation for details about Cookie Groups. Publii's privacy tools do not replace a review of the technologies and legal requirements that apply to your website.

Updating from version 1.x

Version 2.0.0 is a major update designed for current Umami trackers and requires Publii 0.45 or newer. Update Publii before installing the new plugin version if the site uses an older release.

The plugin retains the existing Website ID, tracker script address, automatic tracking, Do Not Track, custom data host, domain list, Preview Mode, Cookie Banner integration, and Cookie Group settings. The new automatic page-view, performance, URL exclusion, tag, and before-send options use their safe defaults until you configure them.

Migration steps

Create a backup of the Publii site before installing the major update.
Confirm that the site uses Publii 0.45 or newer.
Install Umami Analytics Integration 2.0.0, then open its options.
Confirm that Website ID and Tracker script URL still match the tracking code shown by Umami.
Review Allowed domains. Version 2.0.0 fixes this option so it now limits tracking to the listed hostnames. Add every production hostname that should send analytics, including separate root and www variants.
If Cookie Banner integration is enabled, confirm that the banner and advanced configuration are active and that Cookie Group ID exactly matches an existing group. Version 2.0.0 does not output the tracker when this configuration is incomplete.
Review the new options. Keep automatic page views enabled for a standard setup, and enable Core Web Vitals only with Umami 3.1 or newer.
Regenerate the site and test the published output before deploying the update to production.

Removed Cache option

Version 1.x included a Cache option that generated the retired data-cache tracker setting. Current Umami trackers no longer support that setting, so version 2.0.0 removes it without adding a replacement. No migration action is required, even if the old option was enabled.

Stricter validation

Version 2.0.0 validates the Website ID, tracker addresses, domain list, before-send function name, and Cookie Banner configuration before generating code. A value that produced incomplete or unsafe output in version 1.x may now cause the plugin to output nothing. If tracking disappears after the update, review these fields first.

Testing the integration

Regenerate and publish the site to a staging or public URL.
Open the browser's developer tools and select the Network panel.
Reload the page and confirm that the configured tracker script loads without an error.
Open Umami's real-time view and confirm that the test page view appears.
Check that only one page view is recorded for a single page load.
If Allowed domains is configured, repeat the test on every permitted public hostname.
If Cookie Banner integration is enabled, use a new browser profile. Confirm that the Umami script and requests are absent before consent and appear after accepting the selected group.
If Core Web Vitals are enabled, allow enough real visits for performance reports to receive data and confirm that the Umami version supports the feature.

Ad blockers, browser privacy features, Content Security Policy rules, proxy configuration, and consent settings can prevent Umami requests. Test with those factors in mind before changing the plugin configuration.

Preview Mode

The plugin does not output Umami code in Publii Preview unless Output code in Preview Mode is enabled. This default prevents local preview activity from entering analytics reports.

Enable the option temporarily when you need to inspect the generated source or requests. Disable it again after testing and use a staging or public URL for the final check.

Troubleshooting

No Umami code appears in the generated page – Confirm that the plugin is enabled and that the Website ID is a valid UUID. Check the tracker script address and every optional field. If Cookie Banner integration is enabled, verify that the banner, advanced configuration, and selected Cookie Group all exist.
The tracker script does not load – Copy the complete script address from Umami. Use an HTTP or HTTPS URL or a root-relative path beginning with one slash. Remove credentials and URL fragments, then review the browser console, network response, and Content Security Policy.
Umami receives no data although the script loads – Check the custom data host, Allowed domains, automatic tracking settings, consent state, browser extensions, and Umami's real-time report.
Tracking stops after adding Allowed domains – Enter exact hostnames without a protocol, path, port, or wildcard. Include both the root and www hostnames when both serve the website.
Automatic page views continue – Confirm that the site uses Umami 3.2 or newer and that Track page views automatically is disabled. Regenerate and republish the site.
Core Web Vitals do not appear – Confirm that the site uses Umami 3.1 or newer, Initialize automatic tracking is enabled, and Track Core Web Vitals is enabled. Performance reports need real visits before they contain data.
Tracking remains blocked after consent – Check that the Cookie Group ID in the plugin exactly matches the Group ID in Privacy Settings, including capitalization. Confirm that advanced Cookie Banner configuration is enabled.
Reports contain duplicate page views – Check the theme, Custom HTML, Tag Manager, and other plugins for another Umami tracker. Keep one page-view implementation unless duplication is intentional.
The before-send function prevents requests – Confirm that the named global function exists before the tracker starts, does not throw an error, and returns a payload when the request should continue.
Preview visits appear in Umami – Disable Output code in Preview Mode and regenerate the preview.

For tracker behavior and version requirements, see Umami's official guides for tracker configuration, tracker functions, and collecting data.