react-native-clarity

A ReactNative plugin that allows integrating Clarity with your application.

Installation

npm install react-native-clarity

Notes

• The Clarity package depends on native code to run, therefore you have to ship a new build after integrating the package.
• For react-native-svg Users: Clarity is currently incompatible with react-native-svg version 13.x due to a known bug that causes user interaction and playback issues. To ensure proper functionality, please upgrade to react-native-svg version 14 or later.

Usage

import { LogLevel, initialize, setCustomUserId,  setCustomSessionId, setCustomTag, setCurrentScreenName, getCurrentSessionId, getCurrentSessionUrl } from 'react-native-clarity';

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

initialize('<ProjectId>', clarityConfig);

// Pause Clarity capturing.
pause();

// Resume Clarity capturing if paused.
resume();

// Returns true if clarity was paused.
isPaused().then((paused) => {...});

// Set custom user id.
setCustomUserId("<CustomUserId>");

// Set custom session id.
setCustomSessionId("<CustomSessionId>");

// Set custom tag.
setCustomTag("key", "value");

// Setting the current screen name when using React Navigation
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;
        setCurrentScreenName(routeNameRef.current);
      }}
      onStateChange={() => {
        const previousRouteName = routeNameRef.current;
        const currentRouteName = navigationRef.getCurrentRoute().name;

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

// Get current session id to correlate with other tools.
getCurrentSessionId().then((id) => {...});

// Get current session url to correlate with other tools.
getCurrentSessionUrl().then((url) => {...});

Initialization arguments

/**
 * Initializes the Clarity SDK if the API level is supported.
 *
 * @param projectId     [REQUIRED] The Clarity project id to send data to.
 * @param config     [OPTIONAL] The clarity config, if not provided default values are used.
*/
function initialize(projectId: string, config?: ClarityConfig)

/**
 * The configuration that will be used to customize the Clarity behaviour.
 *
 * @param userId        [OPTIONAL default = null] A custom identifier for the current user. If passed as null, the user id
 *                      will be auto generated. The user id in general is sticky across sessions.
 *                      The provided user id must follow these conditions:
 *                          1. Cannot be an empty string.
 *                          2. Should be base36 and smaller than "1Z141Z4".
 * @param logLevel      [OPTIONAL default = LogLevel.None] The level of logging to show in the device logcat stream.
 * @param allowMeteredNetworkUsage  [OPTIONAL default = false] Allows uploading session data to the servers on device metered network.
 * @param enableWebViewCapture    [OPTIONAL default = true] Allows Clarity to capture the web views DOM content.
 * @param allowedDomains    [OPTIONAL default = ["*"]] The whitelisted domains to allow Clarity to capture their DOM content.
 *                          If it contains "*" as an element, all domains will be captured.
 *                          Note: iOS currently does not support allowedDomains feature.
 * @param disableOnLowEndDevices [OPTIONAL default = false] Disable Clarity on low-end devices.
 * @param maximumDailyNetworkUsageInMB [OPTIONAL default = null] Maximum daily network usage for Clarity (null = No limit). When the limit is reached, Clarity will turn on lean mode.
 *                                      Note: iOS currently does not support limiting network usage.
 * @param enableIOS_experimental [OPTIONAL default = false] Experimental flag to enable Clarity on iOS platform.
 */
interface ClarityConfig {
  userId?: string | null;
  logLevel?: LogLevel;
  allowMeteredNetworkUsage?: boolean;
  enableWebViewCapture?: boolean;
  allowedDomains?: string[];
  disableOnLowEndDevices?: Boolean;
  maximumDailyNetworkUsageInMB?: number;
  enableIOS_experimental?: boolean;
}

License

MIT