Osirion.Blazor.Analytics

Osirion.Blazor.Analytics writes the tracking script of an analytics service into your pages. You configure the service once, then place its tracker component in the page head. Trackers render on the server, so they work under Static SSR with no interactive render mode. Each tracker has its own page with its parameters, configuration keys, consent behavior and Content Security Policy sources.

Plausible and Umami are available from 4.1. The Analytics group page compares them.

Install

Install the package, or the Osirion.Blazor meta-package, which includes it:

dotnet add package Osirion.Blazor.Analytics

Setup

Register the services you use in Program.cs:

using Osirion.Blazor.Analytics.Extensions;

builder.Services.AddOsirionAnalytics(analytics => analytics
    .AddGA4(options => options.MeasurementId = "G-XXXXXXXXXX")
    .AddClarity(options => options.SiteId = "your-clarity-project-id"));

Then render the trackers in the <head> of App.razor:

@using Osirion.Blazor.Analytics.Components

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

Configuration

AddOsirionAnalytics(builder.Configuration) registers every service whose section exists under Osirion:Analytics. AddOsirion(builder.Configuration) from the meta-package does the same.

{
  "Osirion": {
    "Analytics": {
      "GA4": { "MeasurementId": "G-XXXXXXXXXX" },
      "Matomo": { "SiteId": "1", "TrackerUrl": "https://analytics.example.com/" }
    }
  }
}

builder.Services.AddOsirionAnalytics(builder.Configuration);

Every service has Enabled (default true) and AutoTrackPageViews (default true); what the second one does differs per tracker, so see the tracker's page for its keys and defaults. To keep tracking off while you develop, set "Enabled": false for the service in appsettings.Development.json.

Tracker parameters override the configured options for one render. A parameter you leave unset keeps the configured value.

Consent gate

The gate is off by default. Turn it on and no tracker script is rendered until the visitor accepted the analytics category in OsirionCookieConsent:

builder.Services.AddOsirionAnalytics(analytics => analytics
    .AddGA4(options => options.MeasurementId = "G-XXXXXXXXXX")
    .RequireConsent());

or in configuration:

{ "Osirion": { "Analytics": { "Consent": { "RequireConsent": true, "Category": "analytics" } } } }

Pass a configure action, such as RequireConsent(options => options.Category = "..."), to check a different category. Consent is read from the consent cookie on the server. The check 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.

The gate covers all six trackers. Providers with their own consent mode react to it: the GA4 tracker sets Google Consent Mode, and the Matomo tracker leaves out its own requireConsent.

Security

Configured values are JSON or attribute encoded before they are written into scripts and attributes. Formats are checked at startup for every enabled service, and a bad value stops the app with a message that names the configuration key; the tracker pages list what each one checks. Most trackers write inline scripts and do not add a nonce, so a Content Security Policy must allow them: see each tracker's page for the addresses it names.

Related

• Analytics components: the six trackers side by side
• Cookie consent: the banner that records the visitor's choice.
• Navigation: enhanced navigation and scroll behavior.
• Osirion.Blazor.Analytics on NuGet