ClarityTracker

ClarityTracker adds the Microsoft Clarity tracking script to a page. Use it when you want Clarity session recordings and heatmaps on a Blazor site. It renders a script, not visible markup, and a live demo would load Microsoft Clarity'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
    .AddClarity(options => options.SiteId = "YOUR_CLARITY_PROJECT_ID"));

@using Osirion.Blazor.Analytics.Components

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

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

{
  "Osirion": {
    "Analytics": {
      "Clarity": { "SiteId": "YOUR_CLARITY_PROJECT_ID" }
    }
  }
}

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 Clarity project 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:

<script type="text/javascript">
    (function (c, l, a, r, i, t, y) {
        c[a] = c[a] || function () { (c[a].q = c[a].q || []).push(arguments) };
        t = l.createElement(r); t.async = 1; t.src = "https://www.clarity.ms/tag/" + i;
        y = l.getElementsByTagName(r)[0]; y.parentNode.insertBefore(t, y);
    })(window, document, "clarity", "script", "YOUR_CLARITY_PROJECT_ID");
</script>

The script address is TrackerUrl followed by the project ID. Both values are JSON-encoded before they are written, so neither can close the script element.

Configuration

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

TrackerUrl is checked at startup when the service is enabled: a value that is not an absolute http(s) address, or protocol-relative, stops the app with a message that names the key. AutoTrackPageViews has no effect on Clarity, which follows history changes itself.

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.

Clarity has no consent API in this tracker: the gate only decides whether the script is written.

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 as well: https://www.clarity.ms by default. The script then makes its own requests to hosts it chooses; this code does not show them, so take them from Microsoft's Clarity documentation.

Behavior

• Rendering. The markup is written only when Enabled is on, SiteId is not blank and TrackerUrl is valid, and, with the consent gate on, the visitor consented.
• Page views. Clarity tracks page views and follows history changes itself, so enhanced navigation needs nothing from Osirion. The tracker emits no page view module.
• Events. The tracker offers no custom event API.

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