Umami Analytics

An unofficial plugin. It is not affiliated with, endorsed by or supported by Umami.

Shows your Umami numbers inside the EmDash admin: site traffic on the dashboard, and page views next to the entries that earned them. For Umami Cloud and a self-hosted Umami from 3.4.0.

• Umami traffic card. On the dashboard: visits, page views and engagement for the last seven days against the week before, and the five most viewed pages with their entries.
• Umami Analytics page. A daily chart over 7, 30 or 90 days, bounce rate and visit time, top entries, referrers, countries, page views by the event data your site attaches (by category, to start with), and a setup check that names the fix for each problem it finds.
• Umami per entry page. Every published entry with its page views over 7 and 30 days, sortable, for one collection or all of them, with translations combined if you like.
• Umami editor panel. Each entry's 7 and 30 day page views beside the editor, and how far readers get when your site sends a read event.
• MCP tools. Four read-only tools that answer from the stored numbers.

The plugin only reads. It never changes anything in Umami or in your content. Demo data lets you try it without an Umami website.

It is tested with a self-hosted Umami 3.4.0. The Umami Cloud connection follows Umami's published API and has not been run against a Cloud account yet.

Based on the EmDash analytics plugin by Eisbachcode, under the MIT licence.

Why does everything show zero? Most setup mistakes give zeroes and no error. Open Plugins > Umami Analytics and select Check setup: it names the fix for each problem it finds.

Why do my numbers differ from Umami's dashboard? Days follow the Time zone setting: use the website's zone in Umami, or daily figures differ near midnight. Pages under /_emdash are left out, and the totals count only the hostnames in Hostnames to count (your site URL and its www form unless changed).

Does it work with Umami Cloud? It follows Umami's published API, but has not been run against a Cloud account. Please report what you find in the repository's issues.

My Umami sits behind a sign-in proxy. Let the plugin's eight Umami API endpoints through without it. The README lists them, and Umami checks the API key on each one.

How many requests does it make? A sync makes at most seven requests to Umami. Opening the Umami Analytics page makes five.

Can I try it without Umami? Yes. Set Data source to Demo data and select Refresh on the dashboard card. It generates 90 days of made-up traffic over your real entries. Switching the data source clears every stored number, so demo figures never mix with real ones.

Who can see the numbers? Editors and admins see the dashboard card, both Umami pages and the MCP tools. Authors see the editor panel for their own entries.

Where do the category tables come from? From event data your site attaches to its page views with the Umami tracker's data-before-send hook. Name up to three properties in Views by event data. A site that sends none sees no tables.

How does read-through work? Your site sends a custom event as a reader reaches each depth of an entry, for example post_read with post and depth. Fill in the four Read-through settings to match. They are empty by default, which turns it off.

Which languages does it speak? English and German, following each user's admin language.

Report a security problem privately through the repository's advisory form: https://github.com/shanelord01/emdash-umami-analytics/security/advisories/new

What the Umami API key can do

An Umami API key has no permissions of its own. It can do whatever the user who created it can do. A key made under an admin user could change or delete every website in your Umami, so create it under a user with the role View only, added to the website's team with the team role View only. A key made that way can read that team's websites and change nothing. The plugin itself only sends GET requests.

Network access

The plugin asks for network:request:unrestricted, because a self-hosted Umami lives on a host you type into the settings, which no fixed list of hosts could name. It only ever requests the Umami API URL from its settings (https://api.umami.is/v1 unless changed), with the key as a Bearer token. Demo data makes no requests at all. EmDash refuses private addresses for every plugin.

What is sent and what is stored

• Umami receives the API key, the website ID and the hostnames to count. Nothing from your content leaves the site.
• The key is saved as an encrypted setting (AES-GCM with EMDASH_ENCRYPTION_KEY). Without that key EmDash refuses to save it rather than store it in plain text. The plugin never writes it to its logs.
• The site's database holds page views and visits per day and path, site totals and engagement per day, the match of each path to its entry with that entry's view counts and read-through, and the sync's state with the last week's top pages, referrers and countries. Daily rows older than Keep daily rows for are deleted.

Who can do what

The dashboard card, the Umami Analytics and Umami per entry pages and the MCP tools need the editor role. The editor panel needs the author role and shows only entries the user may edit. Changing the settings needs the administrator role.

0.1.3, 9 October 2026

• Days follow your time zone. They were UTC days, so a page view before about 10 am in Sydney counted on the day before. The new Time zone setting starts at Australia/Sydney. Set the website's zone in Umami.
• On update the stored numbers are cleared once and read again from Umami, newest first. Charts and views per entry refill over the catch-up: about two hours for 90 days and 100 entries on Node, at the Cron Trigger's pace on Cloudflare Workers. Changing the setting later does the same.
• Named after Umami, so they are not taken for another plugin's: the Umami Analytics and Umami per entry pages (same addresses), the Umami traffic card and the Umami editor panel.
• The registry page has tabs, including this changelog, and a banner.
• Admin fixes: no false "no page is matched", the dashboard's top pages cover its 7 days, the daily chart names its series, and the editor panel names the day its stored history starts.
• No new permissions. The MCP tools now describe their days in your time zone, so EmDash turns Agent access off after the update. Turn it on again under Plugins.

0.1.2, 1 October 2026

• Engagement beside the totals: bounce rate, average visit and pages per visit against the period before, on the Analytics page, the dashboard card and in the site_totals MCP tool.
• Read-through per entry, for sites that send a custom event as a reader reaches each depth. Four new settings, off by default. It shows on the Analytics per entry page, in the editor panel and as reads by day on the Analytics page.
• Faster catch-up after install.
• Two new Umami endpoints: /websites/{id}/event-data/values and /websites/{id}/events/series, used only with read-through on.
• The site_totals answer gained an engagement field. Turn Agent access on again under Plugins after the update.

Full history: CHANGELOG.md.

You need EmDash 1.0.1 or later with a plugin sandbox runner, a website in Umami with Umami's tracking script already on your site, a self-hosted Umami 3.4.0 or later (the first self-hosted release with API keys) or Umami Cloud, and EMDASH_ENCRYPTION_KEY set on the site so the API key can be saved encrypted (npx emdash secrets generate makes one).

1. Install the plugin from the Registry and review its permissions: read content, read the schema, and network requests to any public host. The plugin only ever requests the Umami API URL from its settings.
2. In Umami, create a user with the role View only. Add it to the team that holds your website, with the team role View only. If the website is yours and not a team's, move it to a team first.
3. Sign in to Umami as that user and create a key under Settings > API keys.
4. In EmDash, open Plugins, then this plugin's settings. Paste the key into Umami API key.
5. For a self-hosted Umami, set Umami API URL to https://your-host/api. The default is Umami Cloud's address.
6. Enter the Umami website ID from the website's settings in Umami. Leave it empty and the dashboard card lists the websites the key can see, so you can copy one. Save.
7. Open Plugins > Umami Analytics and select Check setup. It runs through everything the numbers depend on and gives one sentence for each problem.

The first syncs read back as far as Keep daily rows for (90 days by default), newest first. On Node that takes about two hours for a site of 100 entries.

Each collection needs a URL Pattern (under Content Types), or pages cannot be matched to entries. On Cloudflare Workers, the sync needs the Cron Trigger from EmDash's deployment guide.

A self-hosted Umami must be on a public hostname: EmDash refuses private addresses, so localhost, a LAN address or a VPN-only name will not work.

To use the MCP tools, turn on Agent access for the plugin under Plugins. Turn it on again after an update that changes a tool.