@microsoft/react-native-clarity

A React Native plugin that allows integrating Clarity with your application.

Notes

• React Native versions earlier than 0.64 are not supported.
• Platform Support: Android and iOS.
• iOS support was experimental before version 4.0.1 and required enabling the enableIOS_experimental feature flag.
• The Clarity package depends on native code to run. Therefore, you've to ship a new build after integrating the package.
• Expo Go does not support plugins requiring native code to execute. Hence, Clarity SDK doesn't operate if you're running through Expo GO. To run the SDK locally, use the EAS Build system.

Installation

Step 1: Add package dependency

To add the package, run the following command.

npm install @microsoft/react-native-clarity

[iOS Only] Install native dependencies:

cd ios && pod install

Step 2: Initialize Clarity

Initialize Clarity by adding the following.

import * as Clarity from '@microsoft/react-native-clarity';

Clarity.initialize('<project-id>', {
  /* logLevel: Clarity.LogLevel.Verbose, */
});

Step 3: Testing

After integrating Clarity with your application, ensure these steps for testing on a device or a simulator:

1. Your device or simulator should be connected to the internet.
2. The OS version on your device or simulator should be within the supported range specified at Platform/Framework Support Matrix.
3. For initial setup, consider setting the log level to Verbose. This provides detailed logs that can help identify any initialization issues.

Allow approximately 2 hours for complete sessions to appear in your Clarity project on the Clarity website. However, in-progress sessions can still be viewed in real time. See Clarity Recordings in Real Time.

Known issues

• For react-native-svg Users: A known issue in react-native-svg version 13.x affects user interaction and playback when used with Clarity. Upgrade to react-native-svg version 14 or later for proper behavior and compatibility.

Usage

import * as Clarity from '@microsoft/react-native-clarity';

// Initialize Clarity.
const clarityConfig = {
  logLevel: Clarity.LogLevel.Verbose
};

Clarity.initialize('<project-id>', clarityConfig);

// Pauses the Clarity session capturing until a call to the 'resume' function is made.
Clarity.pause();

// Resumes the Clarity session capturing only if it was previously paused by a call to the `pause` function.
Clarity.resume();

// Checks if Clarity session capturing is currently paused based on an earlier call to the `pause` function.
Clarity.isPaused().then((paused) => {...});

// Forces Clarity to start a new session asynchronously.
Clarity.startNewSession(sessionId => {
  // Sets a custom user ID for the current session. This ID can be used to filter sessions on the Clarity dashboard.
  Clarity.setCustomUserId("<CustomUserId>");

  // Sets a custom session ID for the current session. This ID can be used to filter sessions on the Clarity dashboard.
  Clarity.setCustomSessionId("<CustomSessionId>");

  // Sets a custom tag for the current session. This tag can be used to filter sessions on the Clarity dashboard.
  Clarity.setCustomTag("key", "value");
});

// Sends a custom event to the current Clarity session. These custom events can be used to track specific user interactions or actions that Clarity's built-in event tracking doesn't capture.
Clarity.sendCustomEvent('Initialized');

// Sets a callback function that's invoked whenever a new Clarity session starts or an existing session is resumed at app startup.
// If the callback is set after a session has already started, the callback is invoked right away with the current session ID.
Clarity.setOnSessionStartedCallback(sessionId => { });

// Provide a custom screen name tag that's added as a suffix to the base screen name.
Clarity.setCurrentScreenName('Home');

// [DEPRECATED] This function is deprecated and will be removed in a future major version.
// Returns the ID of the currently active Clarity session if a session has already started; otherwise `null`.
Clarity.getCurrentSessionId().then((id) => {...});

// Returns the URL of the current Clarity session recording on the Clarity dashboard if a session has already started; otherwise `null`.
Clarity.getCurrentSessionUrl().then((url) => {...});

Using Clarity With React Navigation

import * as Clarity from '@microsoft/react-native-clarity';
import { NavigationContainer useNavigationContainerRef } from '@react-navigation/native';

const HomeScreen = ({...}) => {
  const navigationRef = useNavigationContainerRef();
  const routeNameRef = React.useRef();

  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => {
        routeNameRef.current = navigationRef.getCurrentRoute().name;
        const clarityConfig = {
          logLevel: Clarity.LogLevel.Verbose
        };

        Clarity.initialize('<project-id>', clarityConfig);
        Clarity.setCurrentScreenName(routeNameRef.current);
      }}
      onStateChange={() => {
        const previousRouteName = routeNameRef.current;
        const currentRouteName = navigationRef.getCurrentRoute().name;

        if (previousRouteName !== currentRouteName) {
          routeNameRef.current = currentRouteName;
          Clarity.setCurrentScreenName(currentRouteName);
        }
      }}
    >
      {/* ... */}
    </NavigationContainer>
  );
};

Initialization arguments

/**
 * @param projectId - The unique identifier assigned to your Clarity project. You can find it on the **Settings** page of Clarity dashboard. This ID is essential for routing data to the correct Clarity project (required).
 * @param config - Configuration of Clarity that tunes the SDK behavior (e.g., what user ID to use, log level, ...etc) (optional).
 *
 * **Notes:**
 * - The initialization function is asynchronous, meaning it returns before Clarity is fully initialized.
 * - For actions that require Clarity to be fully initialized, it's recommended to use the {@linkcode setOnSessionStartedCallback} function.
 */
function initialize(projectId: string, config?: ClarityConfig)

/**
 * A class that allows you to configure the Clarity SDK behavior.
 */
export interface ClarityConfig {
  /**
   * @deprecated This property is deprecated and will be removed in a future major version. Please use {@linkcode setCustomSessionId} instead.
   *
   * The unique identifier associated with the application user. This ID persists across multiple sessions on the same device.
   *
   * **Notes:**
   * - If no {@linkcode userId} is provided, a random one will be generated automatically.
   * - Must be a base-36 string smaller than `1Z141Z4`.
   * - If an invalid {@linkcode userId} is supplied:
   *     - If no `customUserId` is specified, {@linkcode userId} will be used as a `customUserId`, and a new random {@linkcode userId} will be assigned.
   *     - If `customUserId` is specified, the invalid {@linkcode userID} will be ignored.
   * - For more flexibility in user identification, consider using the {@linkcode setCustomUserId} API. However, keep in mind that `customUserId` length must be between 1 and 255 characters.
   */
  userId?: string;

  /**
   * The level of logging to show in the device’s logging stream while debugging. By default, the SDK logs nothing.
   */
  logLevel?: LogLevel;
}

License

MIT