Install or Embed Microsoft Clarity Tag | Blue Frog Docs

Install or Embed Microsoft Clarity Tag

Step-by-step installation guide for Microsoft Clarity across all platforms and content management systems

Install or Embed Microsoft Clarity Tag or SDK

Overview

Installing Microsoft Clarity is straightforward: add a JavaScript snippet to your website's <head> section, and you're done. This guide covers installation methods for every major platform, from manual HTML to WordPress, Shopify, and everything in between.

Choose the method that matches your tech stack and follow the step-by-step instructions.

Prerequisites

Before installing, ensure you have:

  1. Microsoft Clarity account – Sign up at https://clarity.microsoft.com/
  2. Clarity project created – Each website gets its own project
  3. Project ID and tracking code – Found in Clarity dashboard under Settings > Setup
  4. Website access – Ability to edit HTML or install plugins

Getting Your Tracking Code

  1. Log into Clarity dashboard at https://clarity.microsoft.com/
  2. Select your project (or create a new one)
  3. Go to Settings > Setup
  4. Copy the entire tracking code block

Your tracking code looks like this:

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

Note: YOUR_PROJECT_ID will be replaced with your actual project ID.

Installation Methods

Manual HTML Installation

Best for: Static HTML sites, custom applications, developers with direct code access

Step-by-Step Instructions

  1. Open your website's HTML template or main layout file

    • Look for files like index.html, header.php, layout.html, app.html
    • You want the file that's included on every page

  2. Locate the <head> section

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

  3. Paste the Clarity tracking code just before the closing </head> tag

    <head>
  <meta charset="UTF-8">
  <title>Your Website</title>
  <!-- Other head content -->

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

  4. Save the file and deploy to your server

  5. Verify installation:

    • Visit your website
    • Right-click > View Page Source
    • Search for "clarity.ms" to confirm the script is present

WordPress Installation

Best for: WordPress sites of any size

  1. Install the plugin:

    • In WordPress admin, go to Plugins > Add New
    • Search for "Microsoft Clarity"
    • Install Microsoft Clarity by Microsoft
    • Click Activate

  2. Configure the plugin:

    • Go to Settings > Clarity
    • Paste your Project ID (just the ID, not the full script)
    • Click Save Changes

  3. Verify installation:

    • Visit your site
    • Check page source for clarity.ms script

Method 2: Insert Headers and Footers Plugin

If the official plugin doesn't work with your theme:

  1. Install Insert Headers and Footers plugin:

    • Plugins > Add New > Search "Insert Headers and Footers"
    • Install and activate

  2. Add Clarity code:

    • Go to Settings > Insert Headers and Footers
    • Paste the full Clarity tracking code in Scripts in Header section
    • Save

Method 3: Manual Theme Edit

For developers comfortable editing theme files:

  1. Edit theme header:

    • Go to Appearance > Theme File Editor
    • Select header.php (or functions.php for child themes)

  2. Add Clarity code:

    • In header.php: Paste code before </head>
    • In functions.php: Use wp_head hook:
    function add_clarity_tracking() {
?>
  <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>
<?php
}
add_action('wp_head', 'add_clarity_tracking');

  3. Save changes

Shopify Installation

Best for: Shopify stores

  1. Install the Clarity app:

    • Visit Shopify App Store
    • Search "Microsoft Clarity"
    • Install the official Clarity app
    • Authorize the app

  2. Connect your Clarity account:

    • Sign into Microsoft Clarity when prompted
    • Select the project to link to this store
    • Authorize the connection

  3. Verify:

    • Visit your store
    • Check page source for Clarity script

Method 2: Manual Installation (Theme Edit)

  1. Access theme code:

    • In Shopify admin, go to Online Store > Themes
    • Click Actions > Edit Code on your active theme

  2. Edit theme.liquid:

    • In the left sidebar, click Layout > theme.liquid
    • Find the </head> tag
    • Paste Clarity tracking code just before it

  3. Save and verify

Google Tag Manager (GTM)

Best for: Teams managing multiple marketing tags, marketers without developer access

Installation Steps

  1. Create a new tag in GTM:

    • In GTM workspace, go to Tags > New
    • Name the tag: "Microsoft Clarity"

  2. Configure tag:

    • Click Tag Configuration
    • Select Custom HTML
    • Paste your full Clarity tracking code

  3. Set trigger:

    • Click Triggering
    • Select All Pages (or create custom trigger for specific pages)

  4. Save the tag

  5. Preview and test:

    • Click Preview in GTM
    • Visit your website in preview mode
    • Verify the Clarity tag fires on page load
    • Check for errors in GTM debug panel

  6. Publish:

    • Click Submit in GTM
    • Add version name and description
    • Click Publish

  7. Verify:

    • Visit your live site
    • Check that sessions appear in Clarity dashboard within 15 minutes

Other CMS Platforms

Wix

  1. Open Wix Editor
  2. Go to Settings (gear icon on the left) > Custom Code
  3. Click + Add Custom Code
  4. Paste Clarity tracking code
  5. Set:
    • Name: Microsoft Clarity
    • Add Code to Pages: All pages
    • Place Code in: Head
    • Code Type: Essential
  6. Click Apply
  7. Publish your site

Squarespace

  1. In Squarespace dashboard, go to Settings > Advanced > Code Injection
  2. Paste Clarity tracking code in Header section
  3. Click Save
  4. Changes apply immediately to your published site

Webflow

  1. In Webflow project, go to Project Settings > Custom Code
  2. Paste Clarity code in Head Code section
  3. Save settings
  4. Publish your site
  5. Tracking begins immediately on published domain (not Designer preview)

Wix (Alternative: Tracking & Analytics)

  1. In Wix dashboard, go to Settings > Tracking & Analytics
  2. Click + New Tool > Custom
  3. Paste Clarity code
  4. Set to load on all pages
  5. Save and publish

Drupal

  1. Install "Google Analytics" module (it works for any JS snippet)
  2. Go to Configuration > System > Google Analytics
  3. Paste Clarity tracking code in custom code section
  4. Save configuration
  5. Clear cache: Configuration > Development > Performance > Clear all caches

Joomla

  1. Install "Custom HTML" module or edit template directly
  2. Edit template's index.php file:
    • Extensions > Templates > Templates
    • Select your active template
    • Edit index.php
    • Paste Clarity code before </head>
  3. Save and clear cache

Ghost

  1. In Ghost admin, go to Settings > Code Injection
  2. Paste Clarity tracking code in Site Header section
  3. Save
  4. Clarity tracks immediately on your live site

Magento

  1. Go to Content > Configuration
  2. Select your store view
  3. Expand HTML Head section
  4. Paste Clarity code in Scripts and Style Sheets field
  5. Save configuration
  6. Clear cache: System > Cache Management > Flush Magento Cache

BigCommerce

  1. Go to Storefront > Script Manager
  2. Click Create a Script
  3. Configure:
    • Name: Microsoft Clarity
    • Description: Behavior analytics
    • Location: Head
    • Script type: Script
    • Script: Paste Clarity tracking code
    • Pages: All Pages
  4. Save

Single Page Applications (SPAs)

React

Option 1: Add to public/index.html

<!-- public/index.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>React App</title>

    <!-- 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>
    <div id="root"></div>
  </body>
</html>

Option 2: Load programmatically in App.js

// src/App.js
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    // Load Clarity
    (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");
  }, []);

  return <div>Your app content</div>;
}

Vue.js

Add to public/index.html:

<!-- public/index.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Vue App</title>

    <!-- 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>
    <div id="app"></div>
  </body>
</html>

Angular

Add to src/index.html:

<!-- src/index.html -->
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Angular App</title>
  <base href="/">

  <!-- 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>
  <app-root></app-root>
</body>
</html>

Next.js

Add to pages/_document.js:

// pages/_document.js
import { Html, Head, Main, NextScript } from 'next/document';

export default function Document() {
  return (
    <Html>
      <Head>
        {/* Microsoft Clarity */}
        <script
          type="text/javascript"
          dangerouslySetInnerHTML={{
            __html: `
              (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");
            `,
          }}
        />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Verification Steps

After installation, verify Clarity is working:

1. Check Page Source

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

2. Check Browser Console

  • Open DevTools (F12)
  • Go to Console tab
  • No Clarity-related errors should appear

3. Check Network Requests

  • Open DevTools > Network tab
  • Reload the page
  • Filter by "clarity"
  • You should see:
    • https://www.clarity.ms/tag/YOUR_PROJECT_ID (script load)
    • https://www.clarity.ms/collect (data collection)

4. Check Clarity Dashboard

  • Return to Clarity dashboard
  • Go to Dashboard or Recordings
  • Within 5-15 minutes, sessions should appear
  • Click on a recording and verify:
    • Layout renders correctly
    • Clicks are captured
    • No visual glitches

Troubleshooting

Script Not Appearing in Page Source

Possible Causes:

  • Code not saved properly
  • Cache not cleared
  • Code added to wrong template file

Solutions:

  • Double-check file was saved
  • Clear browser cache (Ctrl+Shift+R)
  • Clear CDN/server cache
  • Verify editing the correct template (main layout, not a single page)

No Data in Clarity Dashboard

Possible Causes:

  • Wrong Project ID in code
  • Ad blockers preventing tracking
  • CSP headers blocking script

Solutions:

  • Verify Project ID matches dashboard
  • Test in incognito mode without extensions
  • Update CSP headers to allow clarity.ms
  • See Troubleshooting Guide for detailed fixes

Recordings Show Broken Layout

Possible Causes:

  • CSS hosted on different domain without CORS
  • Shadow DOM or iframes (limited support)

Solutions:

  • Add CORS headers to CSS files
  • Host CSS on same domain as site
  • Accept that Shadow DOM elements may not render perfectly

Best Practices

✅ Do:

  • Place Clarity code in the <head> section
  • Use the official async tracking code from Clarity dashboard
  • Test in staging before production deployment
  • Verify recordings look correct after installation
  • Document where and how you installed Clarity

❌ Don't:

  • Place code at the end of <body> (loads too late)
  • Manually create the script tag (breaks async loading)
  • Install on development environments that aren't publicly accessible
  • Forget to verify data is flowing to Clarity dashboard

Next Steps

After installation:

  1. Configure privacy settings: Setup Guide
  2. Set up custom events: Event Tracking
  3. Integrate with Google Analytics: Integrations Guide
  4. Review first recordings: Learn what users are actually experiencing

Additional Resources:

↑ Back to top
// SYS.FOOTER