mixpanel-react-native 3.1.2 → 3.1.3

package/Samples/MixpanelExpo/.yalc/mixpanel-react-native/index.js

@@ -46,6 +46,8 @@ export class Mixpanel {
     }
     this.token = token;
     this.trackAutomaticEvents = trackAutomaticEvents;
+    this._flags = null; // Lazy-loaded flags instance
+    this.storage = storage; // Store for JavaScript mode
 
     if (useNative && MixpanelReactNative) {
       this.mixpanelImpl = MixpanelReactNative;
@@ -60,27 +62,120 @@ export class Mixpanel {
   }
 
   /**
-   * Initializes Mixpanel
+   * Returns the Flags instance for feature flags operations.
    *
-   * @param {boolean} optOutTrackingDefault Optional Whether or not Mixpanel can start tracking by default. See optOutTracking()
-   * @param {object} superProperties  Optional A Map containing the key value pairs of the super properties to register
-   * @param {string} serverURL Optional Set the base URL used for Mixpanel API requests. See setServerURL()
-   * @param {boolean} useGzipCompression Optional Set whether to use gzip compression for network requests. Defaults to false.
+   * <p>Feature Flags enable dynamic feature control and A/B testing capabilities.
+   * This property is lazy-loaded to avoid unnecessary initialization until first access.
+   *
+   * <p><b>Native Mode Only:</b> Feature flags are currently only available when using native mode
+   * (iOS/Android). JavaScript mode (Expo/React Native Web) support is planned for a future release.
+   *
+   * @return {Flags} an instance of Flags that provides access to feature flag operations
+   * @throws {Error} if accessed in JavaScript mode (when native modules are not available)
+   *
+   * @example
+   * // Check if flags are ready
+   * if (mixpanel.flags.areFlagsReady()) {
+   *   const isEnabled = mixpanel.flags.isEnabledSync('new-checkout', false);
+   * }
+   *
+   * @example
+   * // Get a feature variant value
+   * const buttonColor = mixpanel.flags.getVariantValueSync('button-color', 'blue');
+   *
+   * @see Flags
+   */
+  get flags() {
+    // Enable JS flags for testing via environment variable
+    const jsFlagesEnabled = process.env.MIXPANEL_ENABLE_JS_FLAGS === 'true' ||
+                           process.env.NODE_ENV === 'test';
+
+    // Short circuit for JavaScript mode unless explicitly enabled
+    if (this.mixpanelImpl !== MixpanelReactNative && !jsFlagesEnabled) {
+      throw new Error(
+        "Feature flags are only available in native mode. " +
+        "JavaScript mode support is coming in a future release."
+      );
+    }
+
+    if (!this._flags) {
+      // Lazy load the Flags instance with proper dependencies
+      const Flags = require("./javascript/mixpanel-flags").Flags;
+      this._flags = new Flags(this.token, this.mixpanelImpl, this.storage);
+    }
+    return this._flags;
+  }
+
+  /**
+   * Initializes Mixpanel with optional configuration for tracking, super properties, and feature flags.
+   *
+   * <p>This method must be called before using any other Mixpanel functionality. It sets up
+   * the tracking environment, registers super properties, and optionally initializes feature flags.
+   *
+   * @param {boolean} [optOutTrackingDefault=false] Whether or not Mixpanel can start tracking by default.
+   *     If true, no data will be tracked until optInTracking() is called. See optOutTracking()
+   * @param {object} [superProperties={}] A Map containing the key value pairs of the super properties to register.
+   *     These properties will be sent with every event. Pass {} if no super properties needed.
+   * @param {string} [serverURL="https://api.mixpanel.com"] The base URL used for Mixpanel API requests.
+   *     Use "https://api-eu.mixpanel.com" for EU data residency. See setServerURL()
+   * @param {boolean} [useGzipCompression=false] Whether to use gzip compression for network requests.
+   *     Enabling this reduces bandwidth usage but adds slight CPU overhead.
+   * @param {object} [featureFlagsOptions={}] Feature flags configuration object with the following properties:
+   * @param {boolean} [featureFlagsOptions.enabled=false] Whether to enable feature flags functionality
+   * @param {object} [featureFlagsOptions.context={}] Context properties used for feature flag targeting.
+   *     Can include user properties, device properties, or any custom properties for flag evaluation.
+   *     Note: In native mode, context must be set during initialization and cannot be updated later.
+   * @returns {Promise<void>} A promise that resolves when initialization is complete
+   *
+   * @example
+   * // Basic initialization
+   * const mixpanel = new Mixpanel('YOUR_TOKEN', true);
+   * await mixpanel.init();
+   *
+   * @example
+   * // Initialize with feature flags enabled
+   * const mixpanel = new Mixpanel('YOUR_TOKEN', true);
+   * await mixpanel.init(false, {}, 'https://api.mixpanel.com', false, {
+   *   enabled: true,
+   *   context: {
+   *     platform: 'mobile',
+   *     app_version: '2.1.0'
+   *   }
+   * });
+   *
+   * @example
+   * // Initialize with EU data residency and super properties
+   * await mixpanel.init(
+   *   false,
+   *   { plan: 'premium', region: 'eu' },
+   *   'https://api-eu.mixpanel.com',
+   *   true
+   * );
    */
   async init(
     optOutTrackingDefault = DEFAULT_OPT_OUT,
     superProperties = {},
     serverURL = "https://api.mixpanel.com",
-    useGzipCompression = false
+    useGzipCompression = false,
+    featureFlagsOptions = {}
   ) {
+    // Store feature flags options for later use
+    this.featureFlagsOptions = featureFlagsOptions;
+
     await this.mixpanelImpl.initialize(
       this.token,
       this.trackAutomaticEvents,
       optOutTrackingDefault,
       {...Helper.getMetaData(), ...superProperties},
       serverURL,
-      useGzipCompression
+      useGzipCompression,
+      featureFlagsOptions
     );
+
+    // If flags are enabled AND we're in native mode, initialize them
+    if (featureFlagsOptions.enabled && this.mixpanelImpl === MixpanelReactNative) {
+      await this.flags.loadFlags();
+  }
   }
 
   /**
@@ -109,7 +204,9 @@ export class Mixpanel {
       trackAutomaticEvents,
       optOutTrackingDefault,
       Helper.getMetaData(),
-      "https://api.mixpanel.com"
+      "https://api.mixpanel.com",
+      false,
+      {}
     );
     return new Mixpanel(token, trackAutomaticEvents);
   }

package/Samples/MixpanelExpo/.yalc/mixpanel-react-native/ios/MixpanelReactNative.m

@@ -5,7 +5,7 @@
 
 // MARK: - Mixpanel Instance
 
-RCT_EXTERN_METHOD(initialize:(NSString *)token trackAutomaticEvents:(BOOL)trackAutomaticEvents optOutTrackingByDefault:(BOOL)optOutTrackingByDefault properties:(NSDictionary *)properties serverURL:(NSString *)serverURL resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
+RCT_EXTERN_METHOD(initialize:(NSString *)token trackAutomaticEvents:(BOOL)trackAutomaticEvents optOutTrackingByDefault:(BOOL)optOutTrackingByDefault properties:(NSDictionary *)properties serverURL:(NSString *)serverURL useGzipCompression:(BOOL)useGzipCompression featureFlagsOptions:(NSDictionary *)featureFlagsOptions resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
 
 // Mark: - Settings
 RCT_EXTERN_METHOD(setServerURL:(NSString *)token serverURL:(NSString *)serverURL resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
@@ -105,4 +105,22 @@ RCT_EXTERN_METHOD(groupRemovePropertyValue:(NSString *)token groupKey:(NSString
 
 RCT_EXTERN_METHOD(groupUnionProperty:(NSString *)token groupKey:(NSString *)groupKey groupID:(id)groupID name:(NSString *)name values:(NSArray *)values resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
 
+// MARK: - Feature Flags
+
+RCT_EXTERN_METHOD(loadFlags:(NSString *)token resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD(areFlagsReadySync:(NSString *)token)
+
+RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD(getVariantSync:(NSString *)token featureName:(NSString *)featureName fallback:(NSDictionary *)fallback)
+
+RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD(getVariantValueSync:(NSString *)token featureName:(NSString *)featureName fallbackValue:(id)fallbackValue)
+
+RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD(isEnabledSync:(NSString *)token featureName:(NSString *)featureName fallbackValue:(BOOL)fallbackValue)
+
+RCT_EXTERN_METHOD(getVariant:(NSString *)token featureName:(NSString *)featureName fallback:(NSDictionary *)fallback resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(getVariantValue:(NSString *)token featureName:(NSString *)featureName fallbackValue:(id)fallbackValue resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(isEnabled:(NSString *)token featureName:(NSString *)featureName fallbackValue:(BOOL)fallbackValue resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
+
 @end

package/Samples/MixpanelExpo/.yalc/mixpanel-react-native/ios/MixpanelReactNative.swift

@@ -18,16 +18,39 @@ open class MixpanelReactNative: NSObject {
                     properties: [String: Any],
                     serverURL: String,
                     useGzipCompression: Bool = false,
+                    featureFlagsOptions: [String: Any]?,
                     resolver resolve: RCTPromiseResolveBlock,
                     rejecter reject: RCTPromiseRejectBlock) -> Void {
         let autoProps = properties // copy
         AutomaticProperties.setAutomaticProperties(autoProps)
         let propsProcessed = MixpanelTypeHandler.processProperties(properties: autoProps)
-        Mixpanel.initialize(token: token, trackAutomaticEvents: trackAutomaticEvents, flushInterval: Constants.DEFAULT_FLUSH_INTERVAL,
-                            instanceName: token, optOutTrackingByDefault: optOutTrackingByDefault,
-                            superProperties: propsProcessed,
-                            serverURL: serverURL,
-                            useGzipCompression: useGzipCompression)
+
+        // Handle feature flags options
+        var featureFlagsEnabled = false
+        var featureFlagsContext: [String: Any]? = nil
+
+        if let flagsOptions = featureFlagsOptions {
+            featureFlagsEnabled = flagsOptions["enabled"] as? Bool ?? false
+            featureFlagsContext = flagsOptions["context"] as? [String: Any]
+        }
+
+        // Create MixpanelOptions with all configuration including feature flags
+        let options = MixpanelOptions(
+            token: token,
+            flushInterval: Constants.DEFAULT_FLUSH_INTERVAL,
+            instanceName: token,
+            trackAutomaticEvents: trackAutomaticEvents,
+            optOutTrackingByDefault: optOutTrackingByDefault,
+            useUniqueDistinctId: false,
+            superProperties: propsProcessed,
+            serverURL: serverURL,
+            proxyServerConfig: nil,
+            useGzipCompression: useGzipCompression,
+            featureFlagsEnabled: featureFlagsEnabled,
+            featureFlagsContext: featureFlagsContext ?? [:]
+        )
+
+        Mixpanel.initialize(options: options)
         resolve(true)
     }
 
@@ -460,4 +483,159 @@ open class MixpanelReactNative: NSObject {
         return Mixpanel.getInstance(name: token)
     }
 
+    // MARK: - Feature Flags
+
+    @objc
+    func loadFlags(_ token: String,
+                   resolver resolve: RCTPromiseResolveBlock,
+                   rejecter reject: RCTPromiseRejectBlock) -> Void {
+        guard let instance = MixpanelReactNative.getMixpanelInstance(token),
+              let flags = instance.flags else {
+            resolve(nil)
+            return
+        }
+        flags.loadFlags()
+        resolve(nil)
+    }
+
+    @objc
+    func areFlagsReadySync(_ token: String) -> NSNumber {
+        guard let instance = MixpanelReactNative.getMixpanelInstance(token) else {
+            NSLog("[Mixpanel - areFlagsReadySync: instance is nil for token: \(token)]")
+            return NSNumber(value: false)
+        }
+
+        guard let flags = instance.flags else {
+            NSLog("[Mixpanel - areFlagsReadySync: flags is nil")
+            return NSNumber(value: false)
+        }
+
+        let ready = flags.areFlagsReady()
+        NSLog("[Mixpanel - areFlagsReadySync: flags ready = \(ready)")
+        return NSNumber(value: ready)
+    }
+
+    @objc
+    func getVariantSync(_ token: String,
+                        featureName: String,
+                        fallback: [String: Any]) -> [String: Any] {
+        guard let instance = MixpanelReactNative.getMixpanelInstance(token),
+              let flags = instance.flags else {
+            return fallback
+        }
+
+        let fallbackVariant = convertDictToVariant(fallback)
+        let variant = flags.getVariantSync(featureName, fallback: fallbackVariant)
+        return convertVariantToDict(variant)
+    }
+
+    @objc
+    func getVariantValueSync(_ token: String,
+                             featureName: String,
+                             fallbackValue: Any) -> Any {
+        guard let instance = MixpanelReactNative.getMixpanelInstance(token),
+              let flags = instance.flags else {
+            return fallbackValue
+        }
+
+        return flags.getVariantValueSync(featureName, fallbackValue: fallbackValue) ?? fallbackValue
+    }
+
+    @objc
+    func isEnabledSync(_ token: String,
+                       featureName: String,
+                       fallbackValue: Bool) -> NSNumber {
+        guard let instance = MixpanelReactNative.getMixpanelInstance(token),
+              let flags = instance.flags else {
+            return NSNumber(value: fallbackValue)
+        }
+
+        let enabled = flags.isEnabledSync(featureName, fallbackValue: fallbackValue)
+        return NSNumber(value: enabled)
+    }
+
+    @objc
+    func getVariant(_ token: String,
+                    featureName: String,
+                    fallback: [String: Any],
+                    resolver resolve: @escaping RCTPromiseResolveBlock,
+                    rejecter reject: @escaping RCTPromiseRejectBlock) -> Void {
+        guard let instance = MixpanelReactNative.getMixpanelInstance(token),
+              let flags = instance.flags else {
+            resolve(fallback)
+            return
+        }
+
+        let fallbackVariant = convertDictToVariant(fallback)
+        flags.getVariant(featureName, fallback: fallbackVariant) { variant in
+            resolve(self.convertVariantToDict(variant))
+        }
+    }
+
+    @objc
+    func getVariantValue(_ token: String,
+                         featureName: String,
+                         fallbackValue: Any,
+                         resolver resolve: @escaping RCTPromiseResolveBlock,
+                         rejecter reject: @escaping RCTPromiseRejectBlock) -> Void {
+        guard let instance = MixpanelReactNative.getMixpanelInstance(token),
+              let flags = instance.flags else {
+            resolve(fallbackValue)
+            return
+        }
+
+        flags.getVariantValue(featureName, fallbackValue: fallbackValue) { value in
+            resolve(value)
+        }
+    }
+
+    @objc
+    func isEnabled(_ token: String,
+                   featureName: String,
+                   fallbackValue: Bool,
+                   resolver resolve: @escaping RCTPromiseResolveBlock,
+                   rejecter reject: @escaping RCTPromiseRejectBlock) -> Void {
+        guard let instance = MixpanelReactNative.getMixpanelInstance(token),
+              let flags = instance.flags else {
+            resolve(fallbackValue)
+            return
+        }
+
+        flags.isEnabled(featureName, fallbackValue: fallbackValue) { isEnabled in
+            resolve(isEnabled)
+        }
+    }
+
+    // Helper methods for variant conversion
+    private func convertDictToVariant(_ dict: [String: Any]) -> MixpanelFlagVariant {
+        let key = dict["key"] as? String ?? ""
+        let value = dict["value"] ?? NSNull()
+        let experimentID = dict["experimentID"] as? String
+        let isExperimentActive = dict["isExperimentActive"] as? Bool
+        let isQATester = dict["isQATester"] as? Bool
+
+        return MixpanelFlagVariant(
+            key: key,
+            value: value,
+            isExperimentActive: isExperimentActive,
+            isQATester: isQATester,
+            experimentID: experimentID
+        )
+    }
+
+    private func convertVariantToDict(_ variant: MixpanelFlagVariant) -> [String: Any] {
+        var dict: [String: Any] = [
+            "key": variant.key,
+            "value": variant.value ?? NSNull()
+        ]
+
+        if let experimentID = variant.experimentID {
+            dict["experimentID"] = experimentID
+        }
+        dict["isExperimentActive"] = variant.isExperimentActive
+        dict["isQATester"] = variant.isQATester
+
+        return dict
+    }
+
 }