Microsoft Clarity - Omni-Event Companion

Tagging what matters adds quicker insights to Clarity

This free script helps you get more out of Microsoft Clarity by tagging meaningful events—like button clicks, form activity, downloads, and external link interactions—right inside session recordings. That means you can filter and segment user sessions based on what actually matters, without guessing or sifting through everything.

Whether you're refining a landing page, testing CTAs, or just trying to understand how visitors move through your site, this script gives you sharper behavioral context—with no extra cost or heavy setup. It’s especially useful for teams that care about trust, messaging clarity, and reducing friction in the user experience.

How to install

• Copy and paste the script into a new Custom HTML tag in your Google Tag Manager container.
• Set the trigger to DOM Ready.
• Edit any selectors for your unique site
• Publish your changes.

Option 2 – One-click import:

• Download this JSON file and merge it into your GTM container.
• Set the trigger to your domain's DOM Ready event.
• Edit any selectors for your unique site
• Publish your changes.

<script>
/**
 * Omni-Event Companion Tag for Microsoft Clarity (GTM)
 * Created by Lightkeeper - https://lightkeeper.me
 * Licensed under CC BY 4.0 - https://creativecommons.org/licenses/by/4.0/
 * • Permits: Copying, adapting, sharing, even commercially.
 * • Requires: Attribution (e.g., "Adapted from Lightkeeper project" with a link)
 *
 * Edit selectors for nav, buttons, thank you page, and any others unique to your site
 *
 */
(function () {
  // ======================
  // Editable Settings
  // ======================

  var selectors = {
    navLinks: 'nav a',
    buttons: 'button, .btn, .button',
    formInputs: 'form input, form textarea, form select',
    forms: 'form',
    fileLinks: 'a[href$=".pdf"], a[href$=".doc"], a[href$=".xls"], a[href$=".xlsx"], a[href$=".csv"]',
    externalLinks: 'a[href^="http"]:not([href*="' + location.hostname + '"])',
    mailLinks: 'a[href^="mailto:"]',
    telLinks: 'a[href^="tel:"]'
  };

  // Thank-you page paths
  var thankYouPaths = [
    '/thank-you',
    '/contact/success',
    '/newsletter/thank-you',
    '/alerts/subscribed'
  ];

  // ======================
  // Utility Function
  // ======================

  function sendClarityEvent(eventType, label) {
    if (typeof clarity === 'function') {
      clarity("set", eventType, label);
    }
  }

  // ======================
  // Check for Thank You Page
  // ======================

  var currentPath = window.location.pathname.toLowerCase();
  for (var i = 0; i < thankYouPaths.length; i++) {
    if (thankYouPaths[i] === currentPath) {
      sendClarityEvent("form_submit", "thank_you_page_detected: " + currentPath);
      break;
    }
  }

  // ======================
  // Helper: Add listener to all matched elements
  // ======================

  function addListeners(selector, eventType, callback) {
    var elements = document.querySelectorAll(selector);
    for (var i = 0; i < elements.length; i++) {
      elements[i].addEventListener(eventType, callback, false);
    }
  }

  // ======================
  // Event Listeners
  // ======================

  // Nav link clicks
  addListeners(selectors.navLinks, 'click', function () {
    sendClarityEvent("nav_click", this.textContent ? this.textContent.replace(/\s+/g, ' ').trim() : this.href);
  });

  // Button clicks
  addListeners(selectors.buttons, 'click', function () {
    var label = this.textContent ? this.textContent.replace(/\s+/g, ' ').trim() : '';
    if (!label) {
      label = this.getAttribute('aria-label') || 'button_click';
    }
    sendClarityEvent("button_click", label);
  });

  // Form input focus
  addListeners(selectors.formInputs, 'focus', function () {
    var label = this.name || this.id || 'unknown_input';
    sendClarityEvent("form_input_focus", label);
  });

  // Form submissions
  addListeners(selectors.forms, 'submit', function () {
    var label = this.id || this.name || 'unknown_form';
    sendClarityEvent("form_submit", label);
  });

  // File downloads
  addListeners(selectors.fileLinks, 'click', function () {
    sendClarityEvent("file_download", this.getAttribute('href'));
  });

  // External link clicks
  addListeners(selectors.externalLinks, 'click', function () {
    sendClarityEvent("external_link", this.getAttribute('href'));
  });

  // Email clicks
  addListeners(selectors.mailLinks, 'click', function () {
    sendClarityEvent("email_click", this.getAttribute('href'));
  });

  // Telephone clicks
  addListeners(selectors.telLinks, 'click', function () {
    sendClarityEvent("tel_click", this.getAttribute('href'));
  });

})();
</script>