Skip to main content

Microsoft Clarity Hook

Send feature flag events to Microsoft Clarity session recordings and heatmaps.

Overview​

The @ops-ai/toggly-clarity-hook package automatically sends custom events to Microsoft Clarity when feature flags are evaluated as enabled. This allows you to:

  • Correlate feature flags with user behavior in Clarity sessions
  • Filter session recordings by active features
  • Debug issues by seeing which features were enabled
  • Analyze A/B tests with session replay data

Installation​

$ npm i -s @ops-ai/toggly-clarity-hook

Prerequisites​

  1. Toggly SDK - Any JavaScript-based Toggly SDK with hooks support (v1.0.0+)
  2. Microsoft Clarity - Clarity tracking code must be loaded on your page

How It Works​

The hook implements the afterEvaluation lifecycle event. When a feature flag evaluates to true, it sends:

clarity("event", "FeatureFlag:{flagKey}")

Events are sent immediately (no batching) and only when the result is true.

Usage​

Vanilla JavaScript​

import { Toggly } from '@ops-ai/feature-flags-toggly';
import { ClarityHook } from '@ops-ai/toggly-clarity-hook';

Toggly.init({
  appKey: 'your-app-key',
  environment: 'Production',
  hooks: [
    new ClarityHook({
      eventPrefix: 'FF:',
      checkConsent: () => cookieConsent.analytics
    })
  ]
});

React​

import { createTogglyProvider } from '@ops-ai/react-feature-flags-toggly';
import { ClarityHook } from '@ops-ai/toggly-clarity-hook';

const TogglyProvider = await createTogglyProvider({
  appKey: 'your-app-key',
  environment: 'Production',
  hooks: [new ClarityHook()]
});

Angular​

import { provideToggly } from '@ops-ai/ngx-feature-flags-toggly';
import { ClarityHook } from '@ops-ai/toggly-clarity-hook';

bootstrapApplication(AppComponent, {
  providers: [
    provideToggly({
      appKey: 'your-app-key',
      environment: 'Production',
      hooks: [new ClarityHook()]
    })
  ]
});

Vue​

import { createApp } from 'vue';
import { TogglyPlugin } from 'vue-feature-flags-toggly';
import { ClarityHook } from '@ops-ai/toggly-clarity-hook';

app.use(TogglyPlugin, {
  appKey: 'your-app-key',
  environment: 'Production',
  hooks: [new ClarityHook()]
});

Svelte / Astro / Gatsby​

import { Toggly } from '@ops-ai/feature-flags-toggly';
import { ClarityHook } from '@ops-ai/toggly-clarity-hook';

Toggly.init({
  appKey: 'your-app-key',
  environment: 'Production',
  hooks: [new ClarityHook()]
});

Configuration​

OptionTypeDefaultDescription
enabledbooleantrueEnable or disable the hook
eventPrefixstring"FeatureFlag:"Prefix for Clarity event names
checkConsent() => boolean() => trueConsent callback called before each event

Full Configuration Example​

const clarityHook = new ClarityHook({
  enabled: process.env.NODE_ENV === 'production',
  eventPrefix: 'FF:',
  checkConsent: () => {
    return window.cookieConsent?.analytics ?? false;
  }
});

Privacy & Consent (GDPR/CCPA)​

The checkConsent callback integrates with consent management platforms:

// OneTrust
new ClarityHook({
  checkConsent: () => window.OneTrust?.IsAlertBoxClosed() ?? false
});

// Simple cookie check
new ClarityHook({
  checkConsent: () => document.cookie.includes('analytics_consent=true')
});

Only the feature flag key name is sent to Clarity (e.g., "dark-mode"). No user identifiers, evaluation context, or PII is included.

Viewing in Clarity​

  1. Go to your Microsoft Clarity dashboard
  2. Navigate to Recordings or Heatmaps
  3. Use Filters to search for custom events matching your prefix (e.g., FeatureFlag:*)
  4. Feature events appear in the session recording timeline

Error Handling​

The hook never breaks the Toggly SDK:

  • Clarity API calls are wrapped in try-catch
  • Missing Clarity SDK is handled silently
  • A console warning (not error) is shown if Clarity is not detected at initialization
  • Clarity becoming available after initialization is handled automatically

Dynamic Management​

// Add at runtime
Toggly.addHook(new ClarityHook());

// Remove by name
Toggly.removeHook('clarity-hook');

Troubleshooting​

Events not appearing​

  1. Verify Clarity is loaded: console.log(typeof window.clarity === 'function')
  2. Check your checkConsent callback returns true
  3. Ensure feature flags are evaluating to true
  4. Look for [Toggly Clarity Hook] messages in the console

Console warning at startup​

The warning "Microsoft Clarity not detected" means Clarity was not loaded when the hook was created. The hook will start sending events once Clarity becomes available.

Performance​

  • Overhead: <0.1ms per evaluation
  • Bundle size: ~1KB minified
  • No batching (Clarity handles its own queue)