Hash routing + Heatmaps + Performance metrics

[jullan123]

Hi all!
Is anyone using hash routing in their application and has managed to get Heatmaps and Performance metrics working correctly?

We're seeing a couple of issues:
Heatmaps

• The only page triggered in the start page
• All clicks from the application appear to be aggregated on the start page
• The page preview itself doesn't render and is completely blank

Performance

• Performance metrics don't appear to be accurate either.

Standard analytics and page tracking works, but Heatmaps and Performance don't appear to correctly distinguish between routes.

Has anyone successfully used Heatmaps and Performance with hash routing? If so, did you need any special configuration or workaround to get accurate results?

Any insights would be appreciated.

Thank you!

[DahanItamar]

What you're seeing matches the server code in v3.4.0. Pageviews keep the hash, but Performance and Heatmaps throw it away when they save the path, so every hash route collapses into /.

Where the hash is lost

• Pageviews: /api/send saves pathname + hash for normal events (route.ts#L204-L205), so /#/orders/42 is kept. That's why standard page tracking works for you.
• Performance: the performance branch of the same route saves only pathname (route.ts#L350-L352), so Web Vitals for every route are stored under /.
• Heatmaps: clicks and scrolls go through /api/record. Its getUrlPath also keeps only new URL(url).pathname (record/route.ts#L72-L78), so everything is aggregated on the start page.

I ran those three functions, copied from the v3.4.0 source, on hash URLs:

https://app.example.com/#/orders/42      | pageview: /#/orders/42      | perf: /  | heatmap: /
https://app.example.com/#/settings?tab=2 | pageview: /#/settings?tab=2 | perf: /  | heatmap: /

The blank preview has an extra cause. The heatmap preview isn't a recorded snapshot. It loads your live site in an iframe at your website's domain plus the saved path (getHeatmap.ts#L568). With hash routing that's always https://your-domain/. A preview that's completely blank usually also means the page refuses to be framed, so check X-Frame-Options and the frame-ancestors value in your CSP. They need to allow your Umami origin, and the website's Domain setting has to be filled in.

A workaround for Performance today

The tracker passes every request through the data-before-send hook, including the performance ones (tracker/index.ts#L384-L393). That means you can move the hash route into the path for performance only:

<script>
  function umamiBeforeSend(type, payload) {
    if (type === 'performance' && payload.url) {
      const u = new URL(payload.url, location.href);
      if (u.hash.startsWith('#/')) {
        u.pathname = u.hash.slice(1).split('?')[0];
        u.hash = '';
        payload.url = u.toString();
      }
    }
    return payload;
  }
</script>
<script defer src="https://your-umami/script.js" data-website-id="..." data-performance="true" data-before-send="umamiBeforeSend"></script>

With this, /#/orders/42 is stored as /orders/42 in the Performance report, while pageview URLs are left exactly as they are. I checked it against the copied server logic: /orders/42, /settings and / come out right, and pageviews are unchanged.

Heatmaps can't be fixed from the page. The recorder sends location.href with no hook to rewrite it, and the server drops the hash. That needs a change in Umami: getUrlPath and the performance branch keeping pathname + hash the way the pageview branch already does. It's probably worth opening an issue for, and linking this discussion.

[axiell-hen]

Just to clarify regarding the Performance part: the before-send hook rewrites the URL of an existing performance payload, but does not trigger a new payload on a hash-route change. In a hash-routed SPA, would the workaround therefore attribute the document’s Performance report to the route only when the page is loaded directly on that route, and not generate a new route-specific report when navigating there from / without reloading?