Analytics and Tracking Implementations in Developer Roadmap: Microsoft Clarity, GA4, and FingerprintJS

The developer-roadmap repository implements a comprehensive analytics stack using Microsoft Clarity for heatmap visualization, Google Analytics 4 for event tracking, and FingerprintJS for device identification across its Astro-based static site architecture.

The open-source developer-roadmap project by Kamran Ahmed leverages multiple analytics and tracking implementations to understand user behavior and secure API interactions. Built with Astro, the application embeds third-party tracking scripts at the layout level while maintaining type-safe event tracking through custom TypeScript wrappers.

Microsoft Clarity Integration for Heatmap Analytics

Microsoft Clarity provides session replay and heatmap capabilities to visualize how users interact with the roadmap interface.

Implementation in Clarity.astro

The Clarity script is embedded via an Astro component that injects an inline IIFE (Immediately Invoked Function Expression). This script loads the Clarity SDK asynchronously using the site-specific ID qcw723i36o.

// src/components/Analytics/Clarity.astro
<script type='text/javascript' is:inline>
  (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', 'qcw723i36o');
</script>

The is:inline directive ensures Astro preserves this script as-is during the build process, preventing any bundling that might interfere with the Clarity loader.

Google Analytics 4 and Custom Event Tracking

Google Analytics 4 (GA4) tracks page views and custom events throughout the user journey, from roadmap exploration to progress tracking.

GA4 Script Injection via Analytics.astro

The GA4 implementation resides in src/components/Analytics/Analytics.astro, which loads the global site tag (gtag.js) using the measurement ID G-EZHDT2S2LF.

// src/components/Analytics/Analytics.astro
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-EZHDT2S2LF"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-EZHDT2S2LF');
</script>

Type-Safe Event Tracking with analytics.ts

To maintain type safety and prevent runtime errors, the codebase wraps GA4 event calls in a dedicated TypeScript module at src/components/Analytics/analytics.ts.

// src/components/Analytics/analytics.ts
export function trackEvent(action: string, params?: Record<string, any>) {
  if (!window.gtag) {
    console.warn('gtag not loaded');
    return;
  }

  window.gtag('event', action, {
    ...params,
    // Example: attach current path for better filtering
    page_path: location.pathname,
  });
}

UI components import trackEvent to log specific interactions—such as roadmap node clicks or subscription events—without directly coupling to the gtag global.

FingerprintJS for Device Identification

FingerprintJS provides browser fingerprinting capabilities that enrich API requests with device-level uniqueness, enabling the backend to correlate anonymous sessions.

Browser Fingerprinting in API Requests

The fingerprinting logic is integrated into the HTTP client wrappers located in src/lib/query-http.ts and src/lib/http.ts. When making API calls, the client lazy-loads the FingerprintJS library, generates a visitorId, and attaches it as a custom fp HTTP header.

// src/lib/query-http.ts
import fp from '@fingerprintjs/fingerprintjs';
import Cookies from 'js-cookie';
import { TOKEN_COOKIE_NAME } from './jwt';

export async function httpCall<ResponseType = AppResponse>(
  url: string,
  options?: RequestInit,
): Promise<ResponseType> {
  // Load fingerprint only on the browser
  let visitorId = '';
  if (typeof window !== 'undefined') {
    const fpClient = await fp.load();
    const result = await fpClient.get();
    visitorId = result.visitorId;
  }

  const headers = new Headers({
    Accept: 'application/json',
    Authorization: `Bearer ${Cookies.get(TOKEN_COOKIE_NAME)}`,
    ...(visitorId ? { fp: visitorId } : {}),
    ...(options?.headers ?? {}),
  });

  const response = await fetch(url, { ...options, headers });
  // … error handling omitted for brevity
  return (await response.json()) as ResponseType;
}

The fp header allows the backend to distinguish between unique devices even when users browse anonymously or clear cookies, providing consistent analytics for roadmap progress and feature usage.

Analytics Architecture in Astro

The developer-roadmap project uses Astro's component-based architecture to ensure analytics scripts load on every page without manual repetition.

The src/layouts/BaseLayout.astro file imports both Analytics.astro and Clarity.astro components, placing them in the document <head>. This guarantees that every route rendered through the base layout includes Microsoft Clarity heatmap tracking and Google Analytics page-view instrumentation.

FingerprintJS operates differently—it executes only within the client-side HTTP wrappers when API calls occur, avoiding unnecessary fingerprinting calculations during static site generation.

Summary

• Microsoft Clarity is embedded via src/components/Analytics/Clarity.astro using an inline script with site ID qcw723i36o to capture heatmaps and session replays.
• Google Analytics 4 loads through src/components/Analytics/Analytics.astro with measurement ID G-EZHDT2S2LF, while src/components/Analytics/analytics.ts provides a type-safe trackEvent wrapper.
• FingerprintJS generates a visitorId in src/lib/query-http.ts and src/lib/http.ts, attaching it as an fp header to every API request for device-level tracking.
• All third-party scripts render globally through src/layouts/BaseLayout.astro, ensuring consistent analytics coverage across the Astro static site.

Frequently Asked Questions

What analytics services does the developer-roadmap project use?

The project uses three main services: Microsoft Clarity for heatmap visualization and session recording, Google Analytics 4 for page-view and event tracking, and FingerprintJS for browser fingerprinting to identify unique devices in API requests.

How is Microsoft Clarity implemented in the Astro framework?

Microsoft Clarity is implemented as an Astro component at src/components/Analytics/Clarity.astro that contains an inline IIFE script. This script uses Astro's is:inline directive to prevent bundling and asynchronously loads the Clarity SDK from https://www.clarity.ms/tag/qcw723i36o, ensuring heatmap tracking loads on every page.

What is the purpose of FingerprintJS in this codebase?

FingerprintJS generates a unique visitorId based on browser characteristics to identify devices even when cookies are cleared or users browse anonymously. In src/lib/query-http.ts, this fingerprint attaches as a custom fp HTTP header on every API request, allowing the backend to correlate requests and maintain consistent analytics without requiring user authentication.

Where are the analytics scripts injected in the application lifecycle?

All analytics scripts are injected at the layout level in src/layouts/BaseLayout.astro, which serves as the root layout for all pages. This component imports both Analytics.astro (Google Analytics) and Clarity.astro (Microsoft Clarity), placing them in the document <head> so every route automatically includes tracking code during the static site generation process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}