Microsoft Clarity Setup & Implementation | Blue Frog Docs

Microsoft Clarity Setup & Implementation

Complete guide to implementing Microsoft Clarity tracking, from account creation to production deployment.

Overview

Microsoft Clarity setup is intentionally straightforward. Create a project, add a tracking script to your website, and start collecting behavioral data. Unlike complex analytics platforms that require weeks of configuration, Clarity can be up and running in under 15 minutes.

This guide walks through the complete implementation process, from initial setup to advanced configuration, ensuring you capture quality data while respecting user privacy.

Implementation Phases

Phase 1: Account Creation & Project Setup

Time required: 5 minutes

Create a Microsoft Account (if needed)

Clarity requires a Microsoft account (free):

  1. Go to https://clarity.microsoft.com/
  2. Click Sign up or Sign in
  3. Use an existing Microsoft account (Outlook, Office 365, Xbox, etc.) or create a new one
  4. Accept Clarity's terms of service

Create Your First Project

  1. After signing in, click Add new project
  2. Enter project details:
    • Project name: Descriptive name (e.g., "Company Website Production")
    • Website URL: Your site's primary domain (e.g., https://example.com)
    • Category: Select your industry (optional but helps with benchmarking)
  3. Click Add project

Clarity generates a unique Project ID and tracking code immediately.

Copy Tracking Code

  1. On the project setup screen, Clarity displays installation code
  2. Copy the entire script block (includes your unique Project ID)
  3. Keep this handy for the next phase

Tracking Code Example:

<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>

Phase 2: Installation & Tag Deployment

Time required: 5-10 minutes

Choose your installation method based on your tech stack:

See the detailed Installation Guide for step-by-step instructions for each method.

Quick Start for Manual Installation:

  1. Open your website's main template/header file
  2. Locate the <head> section
  3. Paste Clarity tracking code just before the closing </head> tag
  4. Save and deploy

Example:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Website</title>
  <!-- Other head elements -->

  <!-- Microsoft Clarity -->
  <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>
</head>
<body>
  <!-- Page content -->
</body>
</html>

Phase 3: Verification & QA

Time required: 10-15 minutes

Before rolling out to production, verify Clarity is working correctly.

1. Check Script Installation

View Page Source:

  1. Visit your website
  2. Right-click > View Page Source (or Ctrl+U / Cmd+U)
  3. Search for "clarity.ms" (Ctrl+F / Cmd+F)
  4. Confirm the script appears in the <head> section

Check Browser Console:

  1. Open DevTools (F12 or right-click > Inspect)
  2. Go to Console tab
  3. Look for Clarity-related messages (shouldn't see errors)

2. Verify Data Collection

Check Network Requests:

  1. Open DevTools > Network tab
  2. Reload your website
  3. Filter by "clarity"
  4. Look for:
    • Request to https://www.clarity.ms/tag/YOUR_PROJECT_ID (script load)
    • Requests to https://www.clarity.ms/collect (data collection)

Check Clarity Dashboard:

  1. Return to Clarity dashboard
  2. Go to Dashboard > Overview
  3. Within 5-15 minutes, you should see:
    • Active sessions count increasing
    • Recordings appearing in the Recordings section

Tip: Browse your site for 30+ seconds with several clicks and scrolls to generate a quality session for review.

3. Test Key Pages

Visit critical pages and verify tracking:

  • Homepage
  • Product/service pages
  • Checkout or conversion pages
  • Blog/content pages
  • Mobile view (use DevTools device emulation)

Check for:

  • No console errors
  • Page performance not degraded
  • Forms and interactions still work correctly

4. Review First Recordings

  1. In Clarity dashboard, go to Recordings
  2. Find your test session (filter by recent sessions)
  3. Watch the recording to ensure:
    • Layout appears correctly
    • Clicks are captured
    • Scrolling is tracked
    • No visual glitches or broken content

Phase 4: Privacy & Compliance Configuration

Time required: 10-20 minutes

Configure Clarity to comply with GDPR, CCPA, and your privacy requirements.

Enable Privacy Settings

  1. In Clarity dashboard, go to Settings > Privacy
  2. Configure masking options:
    • Mask sensitive text: ON (recommended)
    • Mask all input fields: ON for sensitive sites (finance, healthcare)
    • Mask all images: ON if images may contain PII

Add Custom Masking

For specific elements that need masking:

<!-- Mask individual elements -->
<input type="text" name="ssn" class="clarity-mask">
<div class="clarity-mask">Sensitive user info here</div>

<!-- Mask entire sections -->
<section class="clarity-mask">
  <h2>Private Member Dashboard</h2>
  <p>User-specific content</p>
</section>

If your region requires user consent before tracking:

<!-- Only load Clarity after user consents -->
<script>
  function loadClarity() {
    (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");
  }

  // Call loadClarity() only after user consent
  if (userHasConsented) {
    loadClarity();
  }
</script>

Integration with consent platforms:

  • OneTrust
  • Cookiebot
  • Custom consent banners

See Integrations guide for specific consent platform examples.

Update Privacy Policy

Add language to your privacy policy:

"We use Microsoft Clarity to understand how you interact with our website. Clarity collects behavioral data such as mouse movements, clicks, and scrolling to help us improve user experience. Clarity automatically masks sensitive information like passwords and payment details. For more information, see Microsoft's privacy statement."

Phase 5: Advanced Configuration

Time required: Varies by complexity

Once basic tracking is working, enhance Clarity with advanced features.

Custom Event Tracking

Mark significant user actions for filtering and analysis:

// Example: Track feature usage
document.getElementById('dark-mode-toggle').addEventListener('click', function() {
  clarity("event", "dark_mode_toggled");
});

// Example: Track checkout step completion
function onCheckoutStepComplete(step) {
  clarity("set", "checkout_step", step);
  clarity("event", "checkout_progress");
}

See Event Tracking Setup for detailed examples.

User Identification

Link sessions to known users (using hashed or anonymized IDs):

// After user login
function onUserLogin(userId) {
  // Hash the user ID to protect privacy
  const hashedId = hashFunction(userId);
  clarity("identify", hashedId);
}

Privacy Warning: Never send PII (emails, names, phone numbers) to Clarity.

Google Analytics Integration

  1. In Clarity dashboard: Settings > Integrations > Google Analytics
  2. Sign in and authorize GA4 connection
  3. Select GA4 property to link
  4. Wait 24-48 hours for data to flow

See Integrations guide for detailed setup.

Cross-Domain Tracking

If your user journey spans multiple domains (e.g., main site → checkout subdomain):

See Cross-Domain Tracking for configuration details.

Phase 6: Production Rollout

Time required: Varies

Deploy Clarity to production with confidence.

  1. Dev/Staging Environment: Test Clarity with full QA process
  2. Canary Deployment: Enable for 10% of production traffic
  3. Monitor for 24-48 hours: Check for performance impact, errors, or data quality issues
  4. Full Rollout: Enable for 100% of users

Performance Monitoring

After deployment, monitor:

  • Page load times: Use Google PageSpeed Insights or Lighthouse
  • Error rates: Check browser console and error tracking tools
  • User complaints: Monitor support channels for issues

Expected impact: Clarity adds 50-100ms to page load time. If you see > 500ms, investigate.

Data Quality Checks

After 48 hours of production data:

  1. Session count: Roughly aligns with your other analytics tools (allow 10-30% variance due to ad blockers)
  2. Recordings quality: Sample 20-30 recordings to ensure layout appears correctly
  3. Heatmaps: Check that heatmaps make sense (clicks on buttons, not random areas)
  4. Insights: Review automatic insights for false positives

Deployment Artifacts & Documentation

Maintain these artifacts for team reference and troubleshooting:

Tracking Plan

Document what Clarity tracks:

Event/Tag Trigger Purpose Owner
checkout_complete Order confirmation page Identify successful purchases Marketing
video_played Video play button click Measure content engagement Content Team
user_type tag After login Segment by user tier Product

Environment Matrix

Track where Clarity is deployed:

Environment Domain Project ID Deployed Date Notes
Production example.com abc123 2024-01-15 Full traffic
Staging staging.example.com xyz789 2024-01-10 QA only
Development localhost def456 2024-01-08 Dev team testing

Access Control

Document who has access:

User Role Permission Level Date Added
jane@example.com Admin Full access 2024-01-15
john@example.com Analyst View only 2024-01-20
dev-team@example.com Developer View + Edit 2024-01-15

Linked Runbooks

Detailed guides for specific implementation aspects:

Common Pitfalls & How to Avoid Them

1. Installing Tracking Code in the Wrong Place

Problem: Code placed in <body> or at the end of </html> doesn't load early enough.

Solution: Always place in <head> section before other scripts.

2. Not Testing Before Full Rollout

Problem: Broken recordings, performance issues, or privacy violations discovered after launch.

Solution: Test in staging, review recordings, check privacy masking before production.

3. Forgetting About Ad Blockers

Problem: Expecting 100% of users to be tracked, then seeing only 70-80%.

Solution: Understand that 10-30% of users block analytics. This is expected.

4. Sending PII Through Custom Events

Problem: Accidentally sending email addresses or names in event parameters.

Solution: Review all custom event implementations. Hash or anonymize any user identifiers.

5. Not Documenting Implementation

Problem: Six months later, no one remembers what events track or why.

Solution: Maintain a tracking plan and update it whenever changes are made.

Change Log & Ownership

Track changes for audit and troubleshooting:

Date Change Who Why
2024-01-15 Initial deployment to production Jane Doe Launch behavior analytics
2024-01-20 Added GA4 integration John Smith Combine quant + qual data
2024-02-01 Enabled strict masking mode Jane Doe GDPR compliance update
2024-02-15 Added checkout_complete event Marketing Team Track conversion flow

Next Steps After Setup

Once Clarity is collecting data:

  1. Watch recordings daily (first week): Familiarize yourself with user behavior patterns
  2. Review automatic insights: Check for rage clicks, dead clicks, JS errors
  3. Create a heatmap review schedule: Weekly heatmap analysis for key pages
  4. Share with team: Invite stakeholders to Clarity project
  5. Integrate with workflow: Make Clarity a regular part of UX reviews, bug reports, and optimization meetings

Quick Reference:

↑ Back to top
// SYS.FOOTER