UmamiTracker

UmamiTracker adds the Umami tracking script to a page. Use it when you measure a Blazor site with Umami Cloud or a self-hosted Umami. It renders a script, not visible markup, and a live demo would load Umami's script on this page, so this page has no demo and shows the markup it renders instead.

Package Osirion.Blazor.Analytics, namespace Osirion.Blazor.Analytics.Components. Source on GitHub. Available from 4.0.

Usage

Register the service once, then place the tracker in the <head> of App.razor, after <HeadOutlet />. It renders on the server, so it works under Static SSR with no interactive render mode.

using Osirion.Blazor.Analytics.Extensions;

builder.Services.AddOsirionAnalytics(analytics => analytics
    .AddUmami(options => options.SiteId = "00000000-0000-0000-0000-000000000000"));

@using Osirion.Blazor.Analytics.Components

<head>
    <meta charset="utf-8" />
    <base href="/" />
    <HeadOutlet />
    <UmamiTracker />
</head>

The same options can come from configuration. AddOsirionAnalytics(builder.Configuration) registers the service when the Osirion:Analytics:Umami section exists:

{
  "Osirion": {
    "Analytics": {
      "Umami": { "SiteId": "00000000-0000-0000-0000-000000000000" }
    }
  }
}

For a self-hosted Umami, also set ScriptUrl to your instance's script (the default is the Umami Cloud script).

A tracker whose service is not registered, or whose required value is missing or invalid, renders nothing.

Parameters

A parameter you leave unset keeps the configured value.

SiteId replaces the configured website ID for this render and must be a GUID. Enabled set to false turns the tracker off for this render.

The last three rows, Theme, Class and Style, come from the component base class and have no effect: the tracker renders no wrapper element.

Rendered markup

With the defaults and these placeholder values (not real ones), the tracker writes:

The website ID is a placeholder (all zeros); copy the real one from Umami.

<script defer src="https://cloud.umami.is/script.js" data-website-id="00000000-0000-0000-0000-000000000000"></script>

This is the whole output: Umami is configured through attributes only, so the tracker writes no inline script. An attribute appears only when its option is set.

Configuration

The keys live under Osirion:Analytics:Umami. Every service also has Enabled (default true) and AutoTrackPageViews (default true).

At startup, when the service is enabled: a non-blank SiteId that is not a GUID, a ScriptUrl that is neither an http(s) address nor a site path, and a HostUrl that is not an absolute http(s) or protocol-relative address stop the app with a message that names the key.

Consent

The consent gate of the package is off by default. Turn it on with RequireConsent() (or Osirion:Analytics:Consent:RequireConsent) and this tracker renders nothing until the visitor accepted the analytics category in OsirionCookieConsent; see the package page for the setup. The check reads the consent cookie on the server and fails closed: with the gate on and no HttpContext, for example inside a component that already runs interactively, the tracker renders nothing. That is why trackers belong in App.razor.

Umami sets no cookies. Whether you still ask for consent is your decision; the gate covers this tracker like the others and, when on, holds the script back until the visitor consented.

Content Security Policy

This tracker writes only an external script tag with no inline script, so it needs no inline allowance. Allow the host of ScriptUrl (https://cloud.umami.is by default) for script-src, and, if you set HostUrl, its host as well. The code only writes HostUrl as an attribute, and the script decides where it sends data, so take the addresses it contacts from Umami's documentation.

Behavior

• Rendering. The markup is written only when Enabled is on, the website ID is a GUID, the addresses are valid and, with the consent gate on, the visitor consented.
• Page views. The script follows history changes itself; the tracker emits no page view module.
• Events. Send custom events from the browser with umami.track() or data-umami-event attributes.

Related

• Analytics components: the six trackers and how they share setup
• Osirion.Blazor.Analytics: install, registration and the consent gate
• Cookie consent: the banner that records the visitor's choice