react-native-clarity 3.1.1 → 4.0.2

package/lib/typescript/index.d.ts

@@ -1,34 +1,28 @@
 /**
- * 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;
 }
 /**
- * The level of logging to show in the device logcat stream.
+ * The level of logging to show in the device logging stream.
  */
 export declare enum LogLevel {
     Verbose = "Verbose",
@@ -39,68 +33,136 @@ export declare enum LogLevel {
     None = "None"
 }
 /**
- * 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 declare function initialize(projectId: string, config?: ClarityConfig): void;
 /**
- * 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 declare function pause(): Promise<boolean | undefined>;
+export declare function pause(): Promise<boolean>;
 /**
- * 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 declare function resume(): Promise<boolean | undefined>;
+export declare function resume(): Promise<boolean>;
 /**
- * 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 declare function isPaused(): Promise<Boolean | undefined>;
+export declare function isPaused(): Promise<boolean>;
 /**
- * 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 declare function setCustomUserId(customUserId: string): Promise<boolean | undefined>;
+export declare function startNewSession(callback: (sessionId: String) => void): void;
 /**
- * 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 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 declare function setCustomSessionId(customSessionId: string): Promise<boolean | undefined>;
+export declare function setCustomUserId(customUserId: string): Promise<boolean>;
 /**
- * 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 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 declare function setCustomTag(key: string, value: string): Promise<boolean | undefined>;
+export declare function setCustomSessionId(customSessionId: string): Promise<boolean>;
 /**
- * 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.
+ * 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 declare function setCurrentScreenName(screenName: string | null): Promise<boolean | undefined>;
+export declare function setCustomTag(key: string, value: string): Promise<boolean>;
 /**
- * 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.
+ * 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 declare function getCurrentSessionId(): Promise<string>;
+export declare function sendCustomEvent(value: string): Promise<boolean>;
 /**
- * Returns the active session url. This can be used to correlate the Clarity session with other
- * analytics tools that the developer may be using.
+ * 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 declare function setOnSessionStartedCallback(callback: (sessionId: String) => void): boolean;
+/**
+ * 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 declare function setCurrentScreenName(screenName: string | null): Promise<boolean>;
+/**
+ * @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 declare function getCurrentSessionId(): Promise<string | undefined>;
+/**
+ * Returns the URL of the current Clarity session recording on the Clarity dashboard if a session has already started; otherwise `undefined`.
+ *
+ * @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`.
  *
- * @returns a promise that resolves to the current session url if there is an active one.
+ * **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 declare function getCurrentSessionUrl(): Promise<string>;
+export declare function getCurrentSessionUrl(): Promise<string | undefined>;
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;GAEG;AACH,oBAAY,QAAQ;IAClB,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,IAAI,SAAS;CACd;AAyBD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,QA6CnE;AAED;;GAEG;AACH,wBAAgB,KAAK,IAAI,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAMpD;AAED;;;GAGG;AACH,wBAAgB,MAAM,IAAI,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAMrD;AAED;;GAEG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAMvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAMlF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAMxF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAMrF;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAM9B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAMrD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAMtD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"AA0BA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAiBD;;GAEG;AACH,oBAAY,QAAQ;IAClB,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,IAAI,SAAS;CACd;AA2ED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,QAiBnE;AAED;;;;GAIG;AACH,wBAAgB,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,CAMxC;AAED;;;;GAIG;AACH,wBAAgB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAMzC;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC,CAM3C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAM3E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAM5E;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMzE;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAM/D;AAKD;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GACpC,OAAO,CAmBT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAMjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAMlE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-clarity",
-  "version": "3.1.1",
+  "version": "4.0.2",
   "description": "A plugin to provide the Clarity experience for the React Native applications.",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -37,8 +37,9 @@
     "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build *.tgz"
   },
   "keywords": [
-    "react-native",
-    "android"
+    "android",
+    "ios",
+    "react-native"
   ],
   "repository": "https://github.com/microsoft/clarity-apps",
   "author": "Microsoft - Clarity <clarity-apps-support@microsoft.com> (https://github.com/microsoft/clarity-apps)",

package/react-native-clarity.podspec

@@ -17,7 +17,7 @@ Pod::Spec.new do |s|
   s.source_files = "ios/**/*.{h,m,mm}"
 
   s.dependency "React-Core"
-  s.dependency "Clarity", '2.2.1'
+  s.dependency "Clarity", '3.0.0'
 
   # Don't install the dependencies when we run `pod install` in the old architecture.
   if ENV['RCT_NEW_ARCH_ENABLED'] == '1' then