react-native-clarity 3.1.1 → 4.0.2

package/src/index.tsx

@@ -1,4 +1,9 @@
-import { NativeModules, Platform } from 'react-native';
+import {
+  NativeModules,
+  NativeEventEmitter,
+  Platform,
+  EmitterSubscription,
+} from 'react-native';
 
 const LINKING_ERROR =
   `The package 'react-native-clarity' doesn't seem to be linked. Make sure: \n\n` +
@@ -9,44 +14,58 @@ const LINKING_ERROR =
   '- You rebuilt the app after installing the package\n' +
   '- You are not using Expo Go\n';
 
+const ReferToDocs =
+  'Please check the docs at https://www.npmjs.com/package/react-native-clarity for assistance.';
+
 const Clarity = NativeModules.Clarity;
+const ClarityEmitter = new NativeEventEmitter(NativeModules.ClarityEmitter);
 
-const SupportedPlatforms = ['android'];
+const SupportedPlatforms = ['android', 'ios'];
 
 let SupportWarningWasShown = false;
 
 /**
- * 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.
+ * A class that allows you to configure the Clarity SDK behavior.
  */
 export interface ClarityConfig {
-  userId?: string | null;
+  /**
+   * @deprecated This property is deprecated and would be removed in a future major version. Use {@linkcode setCustomSessionId} instead.
+   *
+   * The unique identifier associated with the application user. This ID persists across multiple sessions on the same device.
+   *
+   * **Notes:**
+   * - If {@linkcode userId} isn't provided, a random one is generated automatically.
+   * - Must be a base-36 string smaller than `1Z141Z4`.
+   * - If an invalid {@linkcode userId} is supplied:
+   *     - If `customUserId` isn't specified, {@linkcode userId} acts as the `customUserId`, and a new random {@linkcode userId} is assigned.
+   *     - If `customUserId` is specified, the invalid {@linkcode userID} is 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;
-  allowMeteredNetworkUsage?: boolean;
-  enableWebViewCapture?: boolean;
-  allowedDomains?: string[];
-  disableOnLowEndDevices?: Boolean;
-  maximumDailyNetworkUsageInMB?: number;
-  enableIOS_experimental?: boolean;
 }
 
+const ValidConfigKeys = new Set(
+  Object.keys({
+    userId: undefined, // Deprecated.
+    logLevel: undefined,
+  } as ClarityConfig)
+);
+
+const RemovedDynamicConfigKeys = new Set([
+  'allowMeteredNetworkUsage',
+  'enableWebViewCapture',
+  'allowedDomains',
+  'disableOnLowEndDevices',
+  'maximumDailyNetworkUsageInMB',
+]);
+
 /**
- * The level of logging to show in the device logcat stream.
+ * The level of logging to show in the device logging stream.
  */
 export enum LogLevel {
   Verbose = 'Verbose',
@@ -57,15 +76,19 @@ export enum LogLevel {
   None = 'None',
 }
 
+class ClarityError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ClarityError';
+  }
+}
+
 function isClarityUnavailable(): boolean {
   if (!SupportedPlatforms.includes(Platform.OS)) {
-    let warningMessage = 'Clarity supports ' + SupportedPlatforms.join(', ') + ' only for now.';
-    if (Platform.OS === 'ios') {
-      warningMessage = `${warningMessage} To enable experimental iOS support, set the 'enableIOS_experimental' config value to true.`;
-    }
-
     if (!SupportWarningWasShown) {
-      console.warn(warningMessage);
+      console.warn(
+        'Clarity supports ' + SupportedPlatforms.join(', ') + ' only for now.'
+      );
       SupportWarningWasShown = true;
     }
 
@@ -80,177 +103,302 @@ function isClarityUnavailable(): boolean {
   return false;
 }
 
+function validateClarityConfig(config?: ClarityConfig) {
+  if (typeof config === 'undefined') {
+    // Allow using defaults when config is `null` or `undefined`.
+    return;
+  }
+
+  if (typeof config !== 'object') {
+    throw new ClarityError(
+      `Invalid Clarity initialization \`config\` argument. Expected an object, but received ${typeof config}. ${ReferToDocs}`
+    );
+  }
+
+  if (config?.logLevel && !Object.values(LogLevel).includes(config.logLevel)) {
+    console.error(
+      `Invalid ClarityConfig \`logLevel\` property value: ${
+        config.logLevel
+      }. Valid values are: ${Object.values(LogLevel).join(
+        ', '
+      )}. ${ReferToDocs}`
+    );
+  }
+
+  for (const key in config) {
+    if (RemovedDynamicConfigKeys.has(key)) {
+      throw new ClarityError(
+        `The ClarityConfig \`${key}\` property is removed and it's configurable from Clarity dashboard.`
+      );
+    } else if (key === 'enableIOS_experimental') {
+      const errorMessage =
+        'The ClarityConfig `enableIOS_experimental` property is removed and iOS is supported by default.';
+      if ((config as any).enableIOS_experimental) {
+        // Proceed with initialization if the user intended to enable iOS support.
+        console.error(errorMessage);
+      } else {
+        throw new ClarityError(errorMessage);
+      }
+    } else if (key === 'userId') {
+      console.warn(
+        'The ClarityConfig `userId` property is deprecated and would be removed in a future major version. Use `setCustomUserId()` instead.'
+      );
+    } else if (!ValidConfigKeys.has(key)) {
+      console.warn(`Invalid ClarityConfig property: \`${key}\`.`);
+    }
+  }
+}
+
 /**
- * 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.
+ * @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 (for example, which log level to use, and so on).
+ *
+ * **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.
  */
 export function initialize(projectId: string, config?: ClarityConfig) {
-  if (
-    typeof projectId !== 'string' ||
-    !(typeof config === 'object' || typeof config === 'undefined')
-  ) {
-    throw Error(
-      'Invalid Clarity initialization arguments. Please check the docs for assitance.'
+  if (typeof projectId !== 'string') {
+    throw new ClarityError(
+      `Invalid Clarity initialization \`projectId\` argument. Expected a string, but received ${typeof projectId}. ${ReferToDocs}`
     );
   }
 
+  validateClarityConfig(config);
+
   // applying default values
-  let {
-    userId = null,
-    logLevel = LogLevel.None,
-    allowMeteredNetworkUsage = false,
-    enableWebViewCapture = true,
-    allowedDomains = ['*'],
-    disableOnLowEndDevices = false,
-    maximumDailyNetworkUsageInMB = null,
-    enableIOS_experimental = false,
-  } = config ?? {};
-
-  if (enableIOS_experimental === true && !SupportedPlatforms.includes('ios')) {
-    SupportedPlatforms.push('ios');
-  }
+  let { userId = null, logLevel = LogLevel.None } = config ?? {};
 
   if (isClarityUnavailable()) {
     return;
   }
 
-  // We use two parameters because the react method parameters do not accept nullable primitive types.
-  let enableDailyNetworkUsageLimit = maximumDailyNetworkUsageInMB != null;
-  let refinedMaximumDailyNetworkUsageInMB = maximumDailyNetworkUsageInMB ?? 0;
-
-  Clarity.initialize(
-    projectId,
-    userId,
-    logLevel,
-    allowMeteredNetworkUsage,
-    enableWebViewCapture,
-    allowedDomains,
-    disableOnLowEndDevices,
-    enableDailyNetworkUsageLimit,
-    refinedMaximumDailyNetworkUsageInMB
-  );
+  Clarity.initialize(projectId, userId, logLevel);
 }
 
 /**
- * Pauses the Clarity capturing processes until the next resume() is called.
+ * Pauses the Clarity session capturing until a call to the {@linkcode resume} function is made.
+ *
+ * @returns {Promise<boolean>} A Promise that resolves with `true` if Clarity session capturing was paused successfully; otherwise `false`.
  */
-export function pause(): Promise<boolean | undefined> {
+export function pause(): Promise<boolean> {
   if (isClarityUnavailable()) {
-    return Promise.resolve(undefined);
+    return Promise.resolve(false);
   }
 
   return Clarity.pause();
 }
 
 /**
- * Resumes the Clarity capturing processes if they are not already resumed.
- * Note: Clarity starts capturing data right on initialization.
+ * Resumes the Clarity session capturing only if it was previously paused by a call to the {@linkcode pause} function.
+ *
+ * @returns {Promise<boolean>} A Promise that resolves with `true` if Clarity session capturing was resumed successfully; otherwise `false`.
  */
-export function resume(): Promise<boolean | undefined> {
+export function resume(): Promise<boolean> {
   if (isClarityUnavailable()) {
-    return Promise.resolve(undefined);
+    return Promise.resolve(false);
   }
 
   return Clarity.resume();
 }
 
 /**
- * Returns true if Clarity has been paused by the user.
+ * Checks if Clarity session capturing is currently paused based on an earlier call to the {@linkcode pause} function.
+ *
+ * @returns {Promise<boolean>} A Promise that resolves with `true` if Clarity session capturing is currently in the paused state based on an earlier call to the {@linkcode pause} function; otherwise `false`.
  */
-export function isPaused(): Promise<Boolean | undefined> {
+export function isPaused(): Promise<boolean> {
   if (isClarityUnavailable()) {
-    return Promise.resolve(undefined);
+    return Promise.resolve(false);
   }
 
   return Clarity.isPaused();
 }
 
 /**
- * Sets a custom user id that can be used to identify the user. It has less
- * restrictions than the userId parameter. You can pass any string and
- * you can filter on it on the dashboard side. If you need the most efficient
- * filtering on the dashboard, use the userId parameter if possible.
- * <p>
- * Note: custom user id cannot be null or empty, or consists only of whitespaces.
- * </p>
- * @param customUserId   The custom user id to set.
+ * Forces Clarity to start a new session asynchronously.
+ *
+ * @param callback - A callback that is invoked when the new session starts. The callback receives the new session ID as a string parameter.
+ *
+ * **Notes:**
+ * - This function is asynchronous, meaning it returns before the new session is started.
+ * - Use the {@linkcode callback} parameter to execute logic that needs to run after the new session begins.
+ * - Events that occur before invoking the callback are associated with the previous session.
+ * - To ensure proper association of custom tags, user ID, or session ID with the new session, set them within the callback.
  */
-export function setCustomUserId(customUserId: string): Promise<boolean | undefined> {
+export function startNewSession(callback: (sessionId: String) => void): void {
   if (isClarityUnavailable()) {
-    return Promise.resolve(undefined);
+    return;
+  }
+
+  Clarity.startNewSession(callback);
+}
+
+/**
+ * Sets a custom user ID for the current session. This ID can be used to filter sessions on the Clarity dashboard.
+ *
+ * @param customUserId - The custom user ID to associate with the current session. The value must be a nonempty string, with a maximum length of 255 characters, and can't consist only of whitespace.
+ * @returns {Promise<boolean>} A Promise that resolves with `true` if the custom user ID was set successfully; otherwise `false`.
+ *
+ *  **Notes:**
+ *  - To ensure that the custom user ID is associated with the correct session, it's recommended to call this function within the callbacks of {@linkcode setOnSessionStartedCallback} or {@linkcode startNewSession}.
+ *  - Unlike the `userID`, the {@linkcode customUserId} value has fewer restrictions.
+ *  - We recommend **not** to set any Personally Identifiable Information (PII) values inside this field.
+ */
+export function setCustomUserId(customUserId: string): Promise<boolean> {
+  if (isClarityUnavailable()) {
+    return Promise.resolve(false);
   }
 
   return Clarity.setCustomUserId(customUserId);
 }
 
 /**
- * Sets a custom session id that can be used to identify the session.
- * <p>
- * Note: custom session id cannot be null or empty, or consists only of whitespaces.
- * </p>
- * @param customSessionId   The custom session id to set.
+ * Sets a custom session ID for the current session. This ID can be used to filter sessions on the Clarity dashboard.
+ *
+ * @param customSessionId - The custom session ID to associate with the current session. The value must be a nonempty string, with a maximum length of 255 characters, and can't consist only of whitespace.
+ * @returns {Promise<boolean>} A Promise that resolves with `true` if the custom session ID was set successfully; otherwise `false`.
+ *
+ *  **Notes:**
+ *  - To ensure that the custom session ID is associated with the correct session, it's recommended to call this function within the callbacks of {@linkcode setOnSessionStartedCallback} or {@linkcode startNewSession}.
  */
-export function setCustomSessionId(customSessionId: string): Promise<boolean | undefined> {
+export function setCustomSessionId(customSessionId: string): Promise<boolean> {
   if (isClarityUnavailable()) {
-    return Promise.resolve(undefined);
+    return Promise.resolve(false);
   }
 
   return Clarity.setCustomSessionId(customSessionId);
 }
 
 /**
- * Sets a custom tag for the current session.
- * @param key   The tag key to set.
- * @param value   The tag value to set.
+ * Sets a custom tag for the current session. This tag can be used to filter sessions on the Clarity dashboard.
+ *
+ * @param key - The key for the custom tag. The value must be a nonempty string, with a maximum length of 255 characters, and can't consist only of whitespace.
+ * @param value - The value for the custom tag. The value must be a nonempty string, with a maximum length of 255 characters, and can't consist only of whitespace.
+ * @returns {Promise<boolean>} A Promise that resolves with `true` if the custom tag was set successfully; otherwise `false`.
+ *
+ *  **Notes:**
+ *  - To ensure that the custom tag is associated with the correct session, it's recommended to call this function within the callbacks of {@linkcode setOnSessionStartedCallback} or {@linkcode startNewSession}.
  */
-export function setCustomTag(key: string, value: string): Promise<boolean | undefined> {
+export function setCustomTag(key: string, value: string): Promise<boolean> {
   if (isClarityUnavailable()) {
-    return Promise.resolve(undefined);
+    return Promise.resolve(false);
   }
 
   return Clarity.setCustomTag(key, value);
 }
 
 /**
- * For React Native applications only, this function is used to set the current screen name
- * in case the ReactNative Navigation package is used.
- * This will allow you to split and analyze your data on the screen names.
- * You can it set to `null` to remove the latest set value.
- * @param screenName   The current screen name to set.
+ * 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.
+ *
+ * @param value - The name of the custom event. The value must be a nonempty string, with a maximum length of 254 characters, and can't consist only of whitespace.
+ * @returns {Promise<boolean>} A Promise that resolves with `true` if the custom event was sent successfully; otherwise `false`.
+ *
+ * **Notes:**
+ * - This API can be called multiple times per page to track various user actions.
+ * - Each custom event is logged individually and can be filtered, viewed, and analyzed on the Clarity dashboard.
+ */
+export function sendCustomEvent(value: string): Promise<boolean> {
+  if (isClarityUnavailable()) {
+    return Promise.resolve(false);
+  }
+
+  return Clarity.sendCustomEvent(value);
+}
+
+let onSessionStartedSubscription: EmitterSubscription | null = null;
+var onSessionStartedCallback: ((sessionId: string) => void) | null = null;
+
+/**
+ * Sets a callback function that's invoked whenever a new Clarity session starts or an existing session is resumed at app startup.
+ *
+ * @param callback - The callback to be invoked whenever a Clarity session starts. The callback receives the new or resumed session ID as a string parameter.
+ * @returns {boolean} `true` if the callback was set successfully; otherwise `false`.
+ *
+ * **Notes:**
+ * - If the callback is set after a session has already started, the callback is invoked right away with the current session ID.
+ * - The specified callback is guaranteed to run on the main thread.
+ */
+export function setOnSessionStartedCallback(
+  callback: (sessionId: String) => void
+): boolean {
+  if (isClarityUnavailable()) {
+    return false;
+  }
+
+  onSessionStartedCallback = callback;
+
+  if (onSessionStartedSubscription === null) {
+    onSessionStartedSubscription = ClarityEmitter.addListener(
+      'sessionStarted',
+      ({ sessionId }) => {
+        if (onSessionStartedCallback !== null) {
+          onSessionStartedCallback(sessionId);
+        }
+      }
+    );
+  }
+
+  return true;
+}
+
+/**
+ * This function allows you to provide a custom screen name tag that's added as a suffix to the base screen name. The base name is automatically generated based on the current activity in Android, or the currently presented view controller's title or type in iOS.
+ *
+ * @param screenName - The desired screen name tag. The value must be a nonempty string, with a maximum length of 255 characters, and can't consist only of whitespace nor contain `/` character. Set to `null` to reset.
+ * @returns {Promise<boolean>} A Promise that resolves with `true` if the specified screen name tag was set successfully; otherwise `false`.
+ *
+ * **Example:**
+ * - If the presented iOS view controller is a `UIViewController`, and `setCurrentScreenName("Settings")` is called, the screen name is tracked as "UIViewController/Settings".
+ * - If `setCurrentScreenName(nil)` is called on the same view controller, the screen name is tracked as "UIViewController".
+ *
+ * **Notes:**
+ * - Clarity starts a new page whenever either the base screen name (generated from the Android activity or iOS view controller) or the custom name tag changes.
+ * - To mask or disallow a screen, specify the base screen name without the custom tag suffix. For example, to mask the iOS view controller in the previous example, mask the "UIViewController" screen instead of "UIViewController/Settings".
+ * - The screen name tag is set globally and persists across all subsequent Android activities or iOS view controllers until explicitly reset.
  */
 export function setCurrentScreenName(
   screenName: string | null
-): Promise<boolean | undefined> {
+): Promise<boolean> {
   if (isClarityUnavailable()) {
-    return Promise.resolve(undefined);
+    return Promise.resolve(false);
   }
 
   return Clarity.setCurrentScreenName(screenName);
 }
 
 /**
- * Returns the active session id. This can be used to correlate the Clarity session with other
- * analytics tools that the developer may be using.
- * @returns a promise that resolves to the current session id.
+ * @deprecated This function is deprecated and would be removed in a future major version. Use {@linkcode getCurrentSessionUrl} instead.
+ *
+ * Returns the ID of the currently active Clarity session if a session has already started; otherwise `undefined`.
+ *
+ * @returns {Promise<string | undefined>} A Promise that resolves with a string representing the ID of the currently active Clarity session if a session has already started; otherwise `undefined`.
+ *
+ * **Note:**
+ * - The session ID can be used to correlate Clarity sessions with other telemetry services.
+ * - Initially, this function might return `undefined` until a Clarity session begins.
+ * - To ensure a valid session ID, use this method within the callbacks of {@linkcode setOnSessionStartedCallback} or {@linkcode startNewSession}.
  */
-export function getCurrentSessionId(): Promise<string> {
+export function getCurrentSessionId(): Promise<string | undefined> {
   if (isClarityUnavailable()) {
-    return Promise.resolve('Undefined');
+    return Promise.resolve(undefined);
   }
 
   return Clarity.getCurrentSessionId();
 }
 
 /**
- * Returns the active session url. This can be used to correlate the Clarity session with other
- * analytics tools that the developer may be using.
+ * Returns the URL of the current Clarity session recording on the Clarity dashboard if a session has already started; otherwise `undefined`.
  *
- * @returns a promise that resolves to the current session url if there is an active one.
+ * @returns {Promise<string | undefined>} A Promise that resolves with a string representing the URL of the current Clarity session recording on the Clarity dashboard if a session has already started; otherwise `undefined`.
+ *
+ * **Notes:**
+ * - Initially, this function might return `undefined` until a Clarity session begins.
+ * - To ensure a valid session URL, use this method within the callbacks of {@linkcode setOnSessionStartedCallback} or {@linkcode startNewSession}.
  */
-export function getCurrentSessionUrl(): Promise<string> {
+export function getCurrentSessionUrl(): Promise<string | undefined> {
   if (isClarityUnavailable()) {
-    return Promise.resolve('Undefined');
+    return Promise.resolve(undefined);
   }
 
   return Clarity.getCurrentSessionUrl();