Microsoft Clarity Integration

Microsoft Clarity Integration

Microsoft Clarity is a free session recording and heatmap tool. No traffic limits, stores recordings for 90 days, integrates with Google Analytics 4. Works as a replacement for or addition to Hotjar on high-traffic sites.

Installation

Direct insertion:

<!-- Before </head> -->
<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_PROJECT_ID");
</script>

Via GTM: Clarity is in GTM's tag gallery as a ready-made tag type — just enter Project ID.

NPM:

npm install clarity-js

import { clarity } from 'clarity-js';
clarity.start({
  projectId: import.meta.env.VITE_CLARITY_PROJECT_ID,
  upload: 'https://m.clarity.ms/collect',
  expire: 365,
  lean: false,
  track: true,
  content: true,
});

Custom Tags

Clarity allows attaching arbitrary metadata to sessions — similar to identify in other systems:

// Set tags — can be called anytime
window.clarity('set', 'user_id', 'usr_12345');
window.clarity('set', 'plan', 'enterprise');
window.clarity('set', 'page_type', 'product_detail');
window.clarity('set', 'ab_variant', 'B');

// Multiple values for one key
window.clarity('set', 'tag', 'vip');
window.clarity('set', 'tag', 'returning');

Tags are available in filters when viewing recordings: "show sessions where plan = enterprise and page_type = checkout".

User Identification

// Link session to user
window.clarity('identify', 'unique_user_id', 'session_custom_id', 'page_custom_id', 'friendly_name');

// Example for authenticated user
window.clarity(
  'identify',
  user.id,                          // unique user ID
  `session_${Date.now()}`,          // optional session ID
  window.location.pathname,          // optional page ID
  user.email                         // display name in interface
);

Custom Events

// Send event with context
window.clarity('event', 'checkout_started');
window.clarity('event', 'form_error', 'phone_field_invalid');
window.clarity('event', 'video_played', 'intro_video');

Events display in the recording timeline — you can jump to the specific moment when an event occurred.

GA4 Integration

In Clarity settings: "Settings → Integrations → Google Analytics" — select the GA4 property. After activation:

• GA4 gets a custom dimension clarity_session_url with link to Clarity recording
• In Clarity, filter sessions by GA4 segments
• Clarity data visible in GA4 via BigQuery export

SPA and Route Tracking

// React Router
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

export function ClarityRouteTracker() {
  const location = useLocation();

  useEffect(() => {
    // Set tag with current route
    window.clarity?.('set', 'page', location.pathname);
    // Notify of page change
    window.clarity?.('event', 'page_change', location.pathname);
  }, [location.pathname]);

  return null;
}

Data Masking

Clarity automatically masks password fields. For others — use attributes:

<!-- Completely hide element from recordings -->
<div data-clarity-mask="True">
    <span>Passport: 4510 123456</span>
</div>

<!-- Allow showing (if parent is masked) -->
<div data-clarity-mask="True">
    <p>Private data</p>
    <button data-clarity-unmask="True">Public button</button>
</div>

Via project settings: "Settings → Masking" — set "Strict" mode, which masks all text and unmask only needed blocks via data-clarity-unmask.

Using Clarity API

Clarity provides REST API for programmatic data access:

# Get metrics for period
curl -X GET \
  'https://www.clarity.ms/api/v1/projects/YOUR_PROJECT_ID/metrics?startDate=2024-01-01&endDate=2024-01-31' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response contains aggregated data: dead clicks, rage clicks, quick backs, scroll depth for each page.

Installation Verification

// In browser console
window.clarity  // should be a function, not undefined

// Check that script loaded
document.querySelector('script[src*="clarity.ms"]')  // not null

// Force state check
window.clarity('upgrade', 'test_check');

In Clarity interface → "Setup" shows status "Recording" with session count for last 24 hours. First recordings appear within minutes of traffic starting.

Timeline

Installation and verification — 30 minutes. Custom tags and identification setup — 2 hours. GA4 integration and masking configuration — 1 more hour.