MatomoTracker

MatomoTracker adds the Matomo tracking script to a page. Use it when you run Matomo, self-hosted or in the cloud, and want its page views from a Blazor site. It renders a script, not visible markup, and a live demo would load your Matomo server'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.

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
    .AddMatomo(options =>
    {
        options.SiteId = "1";
        options.TrackerUrl = "https://analytics.example.com/";
    }));

@using Osirion.Blazor.Analytics.Components

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

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

{
  "Osirion": {
    "Analytics": {
      "Matomo": { "SiteId": "1", "TrackerUrl": "https://analytics.example.com/" }
    }
  }
}

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 site ID for this render. 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:

analytics.example.com is a placeholder for your Matomo host and 1 for your site ID.

<script>
    var _paq = window._paq = window._paq || [];
    _paq.push(['trackPageView']);
    _paq.push(['enableLinkTracking']);
    (function () {
        var u = "https://analytics.example.com/";
        _paq.push(['setTrackerUrl', u + 'matomo.php']);
        _paq.push(['setSiteId', "1"]);
        var d = document, g = d.createElement('script'), s = d.getElementsByTagName('script')[0];
        g.async = true; g.src = u + 'matomo.js'; s.parentNode.insertBefore(g, s);
    })();
</script>
<script src="/_content/Osirion.Blazor.Analytics/js/osirion-analytics.js" defer data-osirion-analytics="matomo"></script>

The second script is the page view module (see Behavior). Its address is relative, so the document needs a <base href="/" />, which the Blazor templates have.

Configuration

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

TrackerUrl is checked at startup when the service is enabled and not blank: a value that is neither an absolute http(s) address nor protocol-relative stops 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.

With the osirion consent gate on, the script only exists after the visitor consented, so Matomo's own requireConsent is not written even when RequireConsent is true. With the gate off, RequireConsent keeps Matomo silent until your page grants consent in _paq.

Content Security Policy

The tracker writes an inline script and adds no nonce, so script-src must allow inline scripts, or allow this script by its hash. Allow the host of TrackerUrl for script-src (matomo.js) and for the requests to matomo.php. The page view module is an external script from your own site, so it needs no inline allowance.

Behavior

• Rendering. The markup is written only when Enabled is on, SiteId is not blank, TrackerUrl is valid and, with the consent gate on, the visitor consented.
• Page views after enhanced navigation. Blazor enhanced navigation patches the page without a full load, so Matomo would not see the new page. The page view module (/_content/Osirion.Blazor.Analytics/js/osirion-analytics.js) listens for Blazor's enhancedload event and pushes the new referrer, URL, title and a page view onto _paq. Navigation inside a router that already runs interactively does not raise enhancedload and is not reported.
• Events. The tracker offers no custom event API; push to _paq from your own script.

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