react-native-clarity 3.1.1 → 4.0.2

package/README.md

@@ -1,50 +1,108 @@
+**⚠️ This package is on the path to deprecation. Please use @microsoft/react-native-clarity instead for new projects or future updates.**
+
 # react-native-clarity
 
-A ReactNative plugin that allows integrating Clarity with your application.
+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](https://docs.expo.dev/build/setup/) system.
 
 ## Installation
 
-```sh
+### Step 1: Add package dependency
+
+To add the package, run the following command.
+
+```bash
 npm install react-native-clarity
 ```
 
-### Notes
+### Step 2: Initialize Clarity
+
+Initialize Clarity by adding the following.
+
+```typescript
+import * as Clarity from '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](https://learn.microsoft.com/en-us/clarity/mobile-sdk/react-native-sdk#platformframework-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](https://learn.microsoft.com/en-us/clarity/session-recordings/clarity-real-time).
+
+## Known issues
 
-- 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.
+- **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
 
 ```js
-import { LogLevel, initialize, setCustomUserId,  setCustomSessionId, setCustomTag, setCurrentScreenName, getCurrentSessionId, getCurrentSessionUrl } from 'react-native-clarity';
+import * as Clarity from 'react-native-clarity';
 
 // Initialize Clarity.
 const clarityConfig = {
-  logLevel: LogLevel.Verbose,
-  allowMeteredNetworkUsage: true
+  logLevel: Clarity.LogLevel.Verbose
 };
 
-initialize('<ProjectId>', clarityConfig);
+Clarity.initialize('<project-id>', clarityConfig);
 
-// Pause Clarity capturing.
-pause();
+// Pauses the Clarity session capturing until a call to the 'resume' function is made.
+Clarity.pause();
 
-// Resume Clarity capturing if paused.
-resume();
+// Resumes the Clarity session capturing only if it was previously paused by a call to the `pause` function.
+Clarity.resume();
 
-// Returns true if clarity was paused.
-isPaused().then((paused) => {...});
+// Checks if Clarity session capturing is currently paused based on an earlier call to the `pause` function.
+Clarity.isPaused().then((paused) => {...});
 
-// Set custom user id.
-setCustomUserId("<CustomUserId>");
+// 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>");
 
-// Set custom session id.
-setCustomSessionId("<CustomSessionId>");
+  // Sets a custom session ID for the current session. This ID can be used to filter sessions on the Clarity dashboard.
+  Clarity.setCustomSessionId("<CustomSessionId>");
 
-// Set custom tag.
-setCustomTag("key", "value");
+  // Sets a custom tag for the current session. This tag can be used to filter sessions on the Clarity dashboard.
+  Clarity.setCustomTag("key", "value");
+});
 
-// Setting the current screen name when using React Navigation
+// 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
+
+```js
+import * as Clarity from 'react-native-clarity';
 import { NavigationContainer useNavigationContainerRef } from '@react-navigation/native';
 
 const HomeScreen = ({...}) => {
@@ -56,7 +114,12 @@ const HomeScreen = ({...}) => {
       ref={navigationRef}
       onReady={() => {
         routeNameRef.current = navigationRef.getCurrentRoute().name;
-        setCurrentScreenName(routeNameRef.current);
+        const clarityConfig = {
+          logLevel: Clarity.LogLevel.Verbose
+        };
+
+        Clarity.initialize('<project-id>', clarityConfig);
+        Clarity.setCurrentScreenName(routeNameRef.current);
       }}
       onStateChange={() => {
         const previousRouteName = routeNameRef.current;
@@ -64,7 +127,7 @@ const HomeScreen = ({...}) => {
 
         if (previousRouteName !== currentRouteName) {
           routeNameRef.current = currentRouteName;
-          setCurrentScreenName(currentRouteName);
+          Clarity.setCurrentScreenName(currentRouteName);
         }
       }}
     >
@@ -72,53 +135,44 @@ const HomeScreen = ({...}) => {
     </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
 
 ```ts
 /**
- * Initializes the Clarity SDK if the API level is supported.
+ * @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).
  *
- * @param projectId     [REQUIRED] The Clarity project id to send data to.
- * @param config     [OPTIONAL] The clarity config, if not provided default values are used.
-*/
+ * **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)
 
 /**
- * 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.
  */
-interface ClarityConfig {
-  userId?: string | null;
+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;
-  allowMeteredNetworkUsage?: boolean;
-  enableWebViewCapture?: boolean;
-  allowedDomains?: string[];
-  disableOnLowEndDevices?: Boolean;
-  maximumDailyNetworkUsageInMB?: number;
-  enableIOS_experimental?: boolean;
 }
 ```
 

package/android/build.gradle

@@ -69,7 +69,7 @@ def kotlin_version = getExtOrDefault("kotlinVersion")
 dependencies {
   implementation "com.facebook.react:react-native:+"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
-  implementation "com.microsoft.clarity:clarity:2.4.0"
+  implementation "com.microsoft.clarity:clarity:3.0.0"
 }
 
 if (isNewArchitectureEnabled()) {

package/android/src/main/java/com/microsoft/clarity/reactnative/ClarityEmitter.kt

@@ -0,0 +1,55 @@
+package com.microsoft.clarity.reactnative
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.modules.core.DeviceEventManagerModule
+import com.microsoft.clarity.Clarity
+
+internal class ClarityEmitter(private val reactContext: ReactApplicationContext) :
+  ReactContextBaseJavaModule(reactContext) {
+
+  private var listenerCount = 0
+  private var registeredOnSessionStartedCallback = false
+
+  override fun getName(): String {
+    return NAME
+  }
+
+  @ReactMethod
+  fun addListener(eventName: String) {
+    listenerCount += 1
+
+    registerOnSessionStartedCallback()
+  }
+
+  @ReactMethod
+  fun removeListeners(count: Int) {
+    listenerCount -= count
+  }
+
+  private fun registerOnSessionStartedCallback() {
+    // `setOnSessionStartedCallback` should be called:
+    //   - once to maintain the same callback.
+    //   - only when there are listeners so that they can receive the first invocation from the SDK.
+    if (registeredOnSessionStartedCallback) return
+
+    registeredOnSessionStartedCallback = Clarity.setOnSessionStartedCallback { sessionId ->
+      if (listenerCount <= 0) return@setOnSessionStartedCallback
+
+      val params = Arguments.createMap().apply {
+        putString(CLARITY_SESSION_ID_PARAMETER, sessionId)
+      }
+
+      reactContext.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+        .emit(CLARITY_EVENT_SESSION_STARTED, params)
+    }
+  }
+
+  companion object {
+    const val NAME = "ClarityEmitter"
+    const val CLARITY_EVENT_SESSION_STARTED = "sessionStarted"
+    const val CLARITY_SESSION_ID_PARAMETER = "sessionId"
+  }
+}

package/android/src/main/java/com/microsoft/clarity/reactnative/ClarityModule.kt

@@ -20,33 +20,13 @@ class ClarityModule(reactContext: ReactApplicationContext) :
         projectId: String,
         userId: String?,
         logLevel: String,
-        allowMeteredNetworkUsage: Boolean,
-        enableWebViewCapture: Boolean,
-        allowedDomains: ReadableArray,
-        disableOnLowEndDevices: Boolean,
-        enableDailyNetworkUsageLimit: Boolean,
-        maximumDailyNetworkUsageInMB: Double,
         promise: Promise
     ) {
-        val allowedActivities = listOf<String>(); // not supported
-        val disallowedActivities = listOf<String>(); // not supported
-
-        // We use two parameters because the react method parameters do not accept nullable primitive types.
-        // Moreover, the Long data type is not supported. Js numbers are translated into doubles.
-        val maximumDailyNetworkUsageInMBLong = if (enableDailyNetworkUsageLimit) maximumDailyNetworkUsageInMB.toLong() else null
-
         val config = ClarityConfig(
             projectId,
             userId,
             LogLevel.valueOf(logLevel),
-            allowMeteredNetworkUsage,
-            enableWebViewCapture,
-            readableArrayToList(allowedDomains),
-            ApplicationFramework.ReactNative,
-            allowedActivities,
-            disallowedActivities,
-            disableOnLowEndDevices,
-            maximumDailyNetworkUsageInMBLong
+            ApplicationFramework.ReactNative
         )
 
         // Run on the main thread as recommended by the native Clarity SDK.
@@ -74,6 +54,12 @@ class ClarityModule(reactContext: ReactApplicationContext) :
         promise.resolve(Clarity.isPaused())
     }
 
+    @ReactMethod
+    fun startNewSession(callback: Callback) {
+        Clarity.startNewSession {
+            callback.invoke(it)
+        }
+    }
 
     @ReactMethod
     fun setCustomUserId(customUserId: String, promise: Promise) {
@@ -95,6 +81,11 @@ class ClarityModule(reactContext: ReactApplicationContext) :
         promise.resolve(Clarity.setCustomTag(key, value))
     }
 
+    @ReactMethod
+    fun sendCustomEvent(value: String, promise: Promise) {
+        promise.resolve(Clarity.sendCustomEvent(value))
+    }
+
     @ReactMethod
     fun setCurrentScreenName(screenName: String?, promise: Promise) {
         promise.resolve(Clarity.setCurrentScreenName(screenName))
@@ -105,7 +96,6 @@ class ClarityModule(reactContext: ReactApplicationContext) :
         promise.resolve(Clarity.getCurrentSessionUrl())
     }
 
-
     private fun readableArrayToList(arr: ReadableArray): List<String> {
         val ret = mutableListOf<String>()
 

package/android/src/main/java/com/microsoft/clarity/reactnative/ClarityPackage.kt

@@ -8,7 +8,10 @@ import com.facebook.react.uimanager.ViewManager
 
 class ClarityPackage : ReactPackage {
   override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> {
-    return listOf(ClarityModule(reactContext))
+    return listOf(
+      ClarityModule(reactContext),
+      ClarityEmitter(reactContext)
+    )
   }
 
   override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {

package/ios/Clarity.m

@@ -4,17 +4,12 @@
 @import Clarity;
 
 @implementation Clarity
+
 RCT_EXPORT_MODULE()
 
 RCT_EXPORT_METHOD(initialize:(NSString *)projectId
                   userId:(NSString *)userId
                   logLevel:(NSString *)logLevel
-                  allowMeteredNetworkUsage:(BOOL)allowMeteredNetworkUsage
-                  enableWebViewCapture:(BOOL)enableWebViewCapture
-                  allowedDomains:(NSArray *)allowedDomains
-                  disableOnLowEndDevices:(BOOL)disableOnLowEndDevices
-                  enableDailyNetworkUsageLimit:(BOOL)enableDailyNetworkUsageLimit
-                  maximumDailyNetworkUsageInMB:(double)maximumDailyNetworkUsageInMB
                   resolver:(RCTPromiseResolveBlock)resolve
                   rejecter:(RCTPromiseRejectBlock)reject)
 {
@@ -23,29 +18,28 @@ RCT_EXPORT_METHOD(initialize:(NSString *)projectId
 
         config.userId = userId;
         config.logLevel = [self convertLogLevelToEnum:logLevel];
-        config.allowMeteredNetworkUsage = allowMeteredNetworkUsage;
-        config.enableWebViewCapture = enableWebViewCapture;
-        config.disableOnLowEndDevices = disableOnLowEndDevices;
         config.applicationFramework = ApplicationFrameworkReactNative;
 
-        [ClaritySDK initializeWithConfig:config];
+        resolve(@([ClaritySDK initializeWithConfig:config]));
     });
-
-    resolve(@(true));
 }
 
 RCT_EXPORT_METHOD(pause:(RCTPromiseResolveBlock)resolve
                   rejecter:(RCTPromiseRejectBlock)reject)
 {
-    [ClaritySDK pause];
-    resolve(@([ClaritySDK isPaused]));
+    dispatch_async(dispatch_get_main_queue(), ^{
+        [ClaritySDK pause];
+        resolve(@([ClaritySDK isPaused]));
+    });
 }
 
 RCT_EXPORT_METHOD(resume:(RCTPromiseResolveBlock)resolve
                   rejecter:(RCTPromiseRejectBlock)reject)
 {
-    [ClaritySDK resume];
-    resolve(@((BOOL)(![ClaritySDK isPaused])));
+    dispatch_async(dispatch_get_main_queue(), ^{
+        [ClaritySDK resume];
+        resolve(@((BOOL)(![ClaritySDK isPaused])));
+    });
 }
 
 RCT_EXPORT_METHOD(isPaused:(RCTPromiseResolveBlock)resolve
@@ -54,18 +48,31 @@ RCT_EXPORT_METHOD(isPaused:(RCTPromiseResolveBlock)resolve
     resolve(@([ClaritySDK isPaused]));
 }
 
+RCT_EXPORT_METHOD(startNewSession:(RCTResponseSenderBlock)callback)
+{
+    dispatch_async(dispatch_get_main_queue(), ^{
+        [ClaritySDK startNewSessionWithCallback:^(NSString *sessionId) {
+            callback(@[sessionId]);
+        }];
+    });
+}
+
 RCT_EXPORT_METHOD(setCustomUserId:(NSString *)customUserId
                   resolver:(RCTPromiseResolveBlock)resolve
                   rejecter:(RCTPromiseRejectBlock)reject)
 {
-    resolve(@([ClaritySDK setCustomUserId:customUserId]));
+    dispatch_async(dispatch_get_main_queue(), ^{
+        resolve(@([ClaritySDK setCustomUserId:customUserId]));
+    });
 }
 
 RCT_EXPORT_METHOD(setCustomSessionId:(NSString *)customSessionId
                   resolver:(RCTPromiseResolveBlock)resolve
                   rejecter:(RCTPromiseRejectBlock)reject)
 {
-    resolve(@([ClaritySDK setCustomSessionId:customSessionId]));
+    dispatch_async(dispatch_get_main_queue(), ^{
+        resolve(@([ClaritySDK setCustomSessionId:customSessionId]));
+    });
 }
 
 RCT_EXPORT_METHOD(getCurrentSessionId:(RCTPromiseResolveBlock)resolve
@@ -74,6 +81,12 @@ RCT_EXPORT_METHOD(getCurrentSessionId:(RCTPromiseResolveBlock)resolve
     resolve([ClaritySDK getCurrentSessionId]);
 }
 
+RCT_EXPORT_METHOD(getCurrentSessionUrl:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+{
+    resolve([ClaritySDK getCurrentSessionUrl]);
+}
+
 RCT_EXPORT_METHOD(setCustomTag:(NSString *)key value:(NSString *)value
                   resolver:(RCTPromiseResolveBlock)resolve
                   rejecter:(RCTPromiseRejectBlock)reject)
@@ -81,17 +94,20 @@ RCT_EXPORT_METHOD(setCustomTag:(NSString *)key value:(NSString *)value
     resolve(@([ClaritySDK setCustomTagWithKey:key value:value]));
 }
 
-RCT_EXPORT_METHOD(setCurrentScreenName:(NSString *)currentScreenName
+RCT_EXPORT_METHOD(sendCustomEvent:(NSString *)value
                   resolver:(RCTPromiseResolveBlock)resolve
                   rejecter:(RCTPromiseRejectBlock)reject)
 {
-    resolve(@([ClaritySDK setCurrentScreenNameWithName:currentScreenName]));
+    resolve(@([ClaritySDK sendCustomEventWithValue:value]));
 }
 
-RCT_EXPORT_METHOD(getCurrentSessionUrl:(RCTPromiseResolveBlock)resolve
+RCT_EXPORT_METHOD(setCurrentScreenName:(NSString *)currentScreenName
+                  resolver:(RCTPromiseResolveBlock)resolve
                   rejecter:(RCTPromiseRejectBlock)reject)
 {
-    resolve([ClaritySDK getCurrentSessionUrl]);
+    dispatch_async(dispatch_get_main_queue(), ^{
+        resolve(@([ClaritySDK setCurrentScreenName:currentScreenName]));
+    });
 }
 
 - (LogLevel)convertLogLevelToEnum:(NSString*)logLevel

package/ios/Clarity.xcodeproj/project.pbxproj

@@ -8,6 +8,7 @@
 
 /* Begin PBXBuildFile section */
 		6F8543912B793D4F00B05BAC /* Clarity.m in Sources */ = {isa = PBXBuildFile; fileRef = 6F8543902B793D4F00B05BAC /* Clarity.m */; };
+		75415BDF2CC97A5E001213D6 /* ClarityEmitter.m in Sources */ = {isa = PBXBuildFile; fileRef = 75415BDE2CC97A5E001213D6 /* ClarityEmitter.m */; };
 /* End PBXBuildFile section */
 
 /* Begin PBXCopyFilesBuildPhase section */
@@ -26,6 +27,8 @@
 		134814201AA4EA6300B7C361 /* libClarity.a */ = {isa = PBXFileReference; explicitFileType = archive.ar; includeInIndex = 0; path = libClarity.a; sourceTree = BUILT_PRODUCTS_DIR; };
 		6F85438F2B793D4F00B05BAC /* Clarity.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = Clarity.h; sourceTree = "<group>"; };
 		6F8543902B793D4F00B05BAC /* Clarity.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = Clarity.m; sourceTree = "<group>"; };
+		75415BDD2CC97A5E001213D6 /* ClarityEmitter.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = ClarityEmitter.h; sourceTree = "<group>"; };
+		75415BDE2CC97A5E001213D6 /* ClarityEmitter.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = ClarityEmitter.m; sourceTree = "<group>"; };
 /* End PBXFileReference section */
 
 /* Begin PBXFrameworksBuildPhase section */
@@ -52,6 +55,8 @@
 			children = (
 				6F85438F2B793D4F00B05BAC /* Clarity.h */,
 				6F8543902B793D4F00B05BAC /* Clarity.m */,
+				75415BDD2CC97A5E001213D6 /* ClarityEmitter.h */,
+				75415BDE2CC97A5E001213D6 /* ClarityEmitter.m */,
 				134814211AA4EA7D00B7C361 /* Products */,
 			);
 			sourceTree = "<group>";
@@ -115,6 +120,7 @@
 			buildActionMask = 2147483647;
 			files = (
 				6F8543912B793D4F00B05BAC /* Clarity.m in Sources */,
+				75415BDF2CC97A5E001213D6 /* ClarityEmitter.m in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};

package/ios/ClarityEmitter.h

@@ -0,0 +1,6 @@
+#import <React/RCTEventEmitter.h>
+
+
+@interface ClarityEmitter : RCTEventEmitter <RCTBridgeModule>
+
+@end

package/ios/ClarityEmitter.m

@@ -0,0 +1,50 @@
+#import "ClarityEmitter.h"
+#import <React/RCTLog.h>
+
+@import Clarity;
+
+static NSString *const kClarityEventSessionStarted = @"sessionStarted";
+static NSString *const kClaritySessionIdParameter = @"sessionId";
+
+@implementation ClarityEmitter
+{
+    bool hasListeners;
+    bool registeredOnSessionStartedCallback;
+}
+
+RCT_EXPORT_MODULE()
+
+- (NSArray<NSString *> *)supportedEvents {
+    return @[kClarityEventSessionStarted];
+}
+
+// Will be called when this module's first listener is added.
+-(void)startObserving {
+    hasListeners = YES;
+
+    [self registerOnSessionStartedCallback];
+}
+
+// Will be called when this module's last listener is removed, or on dealloc.
+-(void)stopObserving {
+    hasListeners = NO;
+}
+
+- (void)registerOnSessionStartedCallback {
+    // `setOnSessionStartedCallback` should be called:
+    //   - once to maintain the same callback.
+    //   - only when there are listeners so that they can receive the first invocation from the SDK.
+    if (self->registeredOnSessionStartedCallback) {
+        return;
+    }
+
+    self->registeredOnSessionStartedCallback = [ClaritySDK setOnSessionStartedCallback:^(NSString * _Nonnull sessionId) {
+        if (self->hasListeners) { // Only send events if anyone is listening.
+            [self sendEventWithName:kClarityEventSessionStarted body:@{
+                kClaritySessionIdParameter: sessionId
+            }];
+        }
+    }];
+}
+
+@end