react-ms-clarity-controller - Complete Documentation

A comprehensive React wrapper for Microsoft Clarity with advanced features and full control over tracking, recording, and user identification.

✨ Features

✅ Dynamic Control - Enable/disable, pause/resume, start/stop recording
✅ Advanced User Identification - Track users with custom IDs, emails, metadata
✅ Event Tracking - Custom events with structured data
✅ Session Management - Custom session IDs, session upgrades, metadata access
✅ Privacy Controls - Cookie consent management, content masking
✅ React Native Support - Works with WebView for mobile apps
✅ TypeScript Support - Full type definitions included
✅ Development Mode - Optional enable/disable in development
✅ Tag Management - Custom tags for filtering and segmentation
✅ Zero Dependencies - Lightweight and performant

🚀 Installation

npm install react-ms-clarity-controller

or

yarn add react-ms-clarity-controller

📖 Quick Start

1. Basic Setup with Provider

import { ClarityProvider } from "react-ms-clarity-controller";

function App() {
  return (
    <ClarityProvider projectId="YOUR_PROJECT_ID" autoLoad={true}>
      <YourApp />
    </ClarityProvider>
  );
}

2. Using the Hook

import { useClarity } from "react-ms-clarity-controller";

function MyComponent() {
  const { enabled, isLoaded, enable, disable, identify, event } = useClarity();

  const handleLogin = (user) => {
    // Identify user
    identify({
      userId: user.id,
      friendlyName: user.name,
      email: user.email,
    });

    // Track event
    event("user_login", { method: "email" });
  };

  return (
    <div>
      <p>Clarity Status: {isLoaded ? "Loaded" : "Not Loaded"}</p>
      <button onClick={enable}>Enable Tracking</button>
      <button onClick={disable}>Disable Tracking</button>
    </div>
  );
}

🎯 Advanced Configuration

Provider Props

<ClarityProvider
  projectId="YOUR_PROJECT_ID"
  autoLoad={false}
  enableInDev={true}
  config={{
    cookieConsent: "required",
    mask: {
      selectors: [".sensitive", "#password"],
      maskAllText: false,
      maskAllInputs: true,
    },
    customSessionId: "custom-session-123",
    onLoad: () => console.log("Clarity loaded"),
    onError: (error) => console.error("Clarity error:", error),
  }}
  initialUserData={{
    userId: "user-123",
    friendlyName: "John Doe",
  }}
  initialTags={{
    plan: "premium",
    region: "us-east",
  }}
>
  <App />
</ClarityProvider>

See the full documentation in DOCUMENTATION.md for all configuration options, API reference, examples, and best practices.