Skip to main content

Microsoft Clarity Setup Guide

Overview​

Microsoft Clarity has been integrated into this Docusaurus website to provide behavioral analytics, session replays, and heatmaps.

Configuration​

1. Get Your Clarity Project ID​

  1. Go to Microsoft Clarity
  2. Sign in or create an account
  3. Create a new project or select an existing one
  4. Navigate to Settings > Setup
  5. Copy your Project ID

2. Configure the Website​

Edit docusaurus.config.js and replace YOUR_CLARITY_PROJECT_ID with your actual project ID:

themeConfig: {
  // Microsoft Clarity configuration
  clarityProjectId: 'YOUR_ACTUAL_PROJECT_ID_HERE',
  // ... rest of config
}

3. Environment Variables (Optional)​

For better security, you can use environment variables:

  1. Create a .env file in the root directory:
CLARITY_PROJECT_ID=your_actual_project_id
  1. Update docusaurus.config.js:
clarityProjectId: process.env.CLARITY_PROJECT_ID || 'YOUR_CLARITY_PROJECT_ID',

Features Implemented​

Automatic Tracking​

  • Page Views: All page navigations are automatically tracked
  • Custom Tags: Pages are tagged by type (blog, documentation, homepage)
  • Section Tracking: Site sections are automatically tagged

Available Clarity APIs​

The integration provides utility functions for advanced tracking:

import { 
  identifyUser, 
  setCustomTag, 
  trackEvent, 
  setCookieConsent,
  upgradeSession 
} from '@site/src/utils/clarity';

// Identify a user (ID will be hashed)
identifyUser('user123', 'session456', 'page789', 'John Doe');

// Set custom tags for filtering
setCustomTag('user-type', 'premium');
setCustomTag('feature', ['search', 'export']);

// Track custom events
trackEvent('download-started');
trackEvent('form-submitted');

// Manage cookie consent
setCookieConsent(true); // or false

// Prioritize important sessions
upgradeSession('checkout-started');

Testing the Integration​

Development Mode​

  1. Start the development server:
yarn start
  1. Open browser console and look for:
✅ Microsoft Clarity initialized

Production Build​

  1. Build the site:
yarn build
  1. Serve locally:
yarn serve
  1. Check the Network tab in browser DevTools for requests to clarity.ms

Verifying in Clarity Dashboard​

After deployment:

  1. Go to your Clarity Dashboard
  2. Select your project
  3. You should see:
    • Active sessions appearing in real-time
    • Recordings available after a few minutes
    • Heatmaps generated after sufficient data collection

Privacy Considerations​

  • Clarity automatically masks sensitive content
  • Personal data is hashed before transmission
  • IP addresses are anonymized by default
  • Users can be excluded via cookie consent management

Troubleshooting​

Clarity Not Loading​

  • Verify the Project ID is correct
  • Check browser console for errors
  • Ensure the site is deployed (localhost works for testing)
  • Check ad blockers aren't interfering

No Data in Dashboard​

  • Wait 2-5 minutes for data to appear
  • Verify the Project ID matches your Clarity project
  • Check that JavaScript is enabled
  • Ensure cookies are not blocked

Additional Resources​