mixpanel-react-native 3.1.2 → 3.1.3

package/Samples/MixpanelExpo/.yalc/mixpanel-react-native/README.md

@@ -1,29 +1,29 @@
-
-
 <div align="center" style="text-align: center">
   <img src="https://user-images.githubusercontent.com/71290498/231855346-12c8fc52-5f24-485c-b9e6-24468599fb87.png" alt="Mixpanel React Native Library" height="150"/>
 </div>
 
-##### 
+#####
+
 ## Table of Contents
 
 <!-- MarkdownTOC -->
+
 - [Introduction](#introduction)
 - [Quick Start Guide](#quick-start-guide)
-    - [Install Mixpanel](#1-install-mixpanel)
-    - [Initialize Mixpanel](#2-initialize-mixpanel)
-    - [Send Data](#3-send-data)
-    - [Check for Success](#4-check-for-success)
-    - [Complete Code Example](#complete-code-example)
+  - [Install Mixpanel](#1-install-mixpanel)
+  - [Initialize Mixpanel](#2-initialize-mixpanel)
+  - [Send Data](#3-send-data)
+  - [Check for Success](#4-check-for-success)
+  - [Complete Code Example](#complete-code-example)
 - [FAQ](#faq)
 - [I want to know more!](#i-want-to-know-more)
 
 <!-- /MarkdownTOC -->
 
-
 ## Introduction
+
 Welcome to the official Mixpanel React Native library.
-The Mixpanel React Native library is an open-source project, and we'd love to see your contributions! 
+The Mixpanel React Native library is an open-source project, and we'd love to see your contributions!
 We'd also love for you to come and work with us! Check out **[Jobs](https://mixpanel.com/jobs/#openings)** for details.
 
 ## Quick Start Guide
@@ -31,56 +31,71 @@ We'd also love for you to come and work with us! Check out **[Jobs](https://mixp
 Mixpanel's React Native SDK is a wrapper around Mixpanel’s native iOS and Android SDKs and it supports offline tracking. Check out our **[official documentation](https://developer.mixpanel.com/docs/react-native)** for more in depth information on installing and using Mixpanel on React Native.
 
 <a name="installation"></a>
+
 ### 1. Install Mixpanel
+
 #### Prerequisites
+
 - React Native v0.6+
 - [Setup development environment for React Native](https://reactnative.dev/docs/environment-setup)
+
 #### Steps
-1. Under your app's root directory, install Mixpanel React Native SDK. 
+
+1. Under your app's root directory, install Mixpanel React Native SDK.
+
 ```
 npm install mixpanel-react-native
 ```
+
 2. Under your application's ios folder, run
+
 ```
 pod install
-``` 
-Please note: You do not need to update your Podfile to add Mixpanel. 
+```
 
-3. Since Xcode 12.5, there is a known swift compile issue, please refer to this **[workaround](https://github.com/mixpanel/mixpanel-react-native/issues/43#issuecomment-829599732)**. However the compile issue has been resolved in Xcode 13.2.1+, there is no extra step required as long as you upgrade to Xcode 13.2.1+.
+Please note: You do not need to update your Podfile to add Mixpanel.
 
+3. Since Xcode 12.5, there is a known swift compile issue, please refer to this **[workaround](https://github.com/mixpanel/mixpanel-react-native/issues/43#issuecomment-829599732)**. However the compile issue has been resolved in Xcode 13.2.1+, there is no extra step required as long as you upgrade to Xcode 13.2.1+.
 
 ### 2. Initialize Mixpanel
+
 To start tracking with the library you must first initialize with your project token. You can get your project token from [project settings](https://mixpanel.com/settings/project).
 
 ```js
-import { Mixpanel } from 'mixpanel-react-native';
+import { Mixpanel } from "mixpanel-react-native";
 
 const trackAutomaticEvents = false;
 const mixpanel = new Mixpanel("Your Project Token", trackAutomaticEvents);
 mixpanel.init();
-
 ```
+
 Once you've called this method once, you can access `mixpanel` throughout the rest of your application.
+
 ### 3. Send Data
+
 Let's get started by sending event data. You can send an event from anywhere in your application. Better understand user behavior by storing details that are specific to the event (properties). After initializing the library, Mixpanel will automatically track some properties by default. [learn more](https://help.mixpanel.com/hc/en-us/articles/115004613766-Default-Properties-Collected-by-Mixpanel)
+
 ```js
 // Track with event-name
-mixpanel.track('Sent Message');
+mixpanel.track("Sent Message");
 // Track with event-name and property
-mixpanel.track('Plan Selected', {'Plan': 'Premium'});
+mixpanel.track("Plan Selected", { Plan: "Premium" });
 ```
+
 In addition to event data, you can also send [user profile data](https://developer.mixpanel.com/docs/react-native#storing-user-profiles). We recommend this after completing the quickstart guide.
+
 ### 4. Check for Success
-[Open up Events in Mixpanel](http://mixpanel.com/report/events)  to view incoming events.
+
+[Open up Events in Mixpanel](http://mixpanel.com/report/events) to view incoming events.
 Once data hits our API, it generally takes ~60 seconds for it to be processed, stored, and queryable in your project.
 <a name="i-want-to-know-more"></a>
 
 ### Complete Code Example
-```js
 
-import React from 'react';
+```js
+import React from "react";
 import { Button, SafeAreaView } from "react-native";
-import { Mixpanel } from 'mixpanel-react-native';
+import { Mixpanel } from "mixpanel-react-native";
 
 const trackAutomaticEvents = false;
 const mixpanel = new Mixpanel("Your Project Token", trackAutomaticEvents);
@@ -91,27 +106,59 @@ const SampleApp = () => {
     <SafeAreaView>
       <Button
         title="Select Premium Plan"
-        onPress={() => mixpanel.track("Plan Selected", {"Plan": "Premium"})}
+        onPress={() => mixpanel.track("Plan Selected", { Plan: "Premium" })}
       />
     </SafeAreaView>
   );
-}
+};
 
 export default SampleApp;
+```
+
+### Feature Flags (Beta - 3.2.0-beta.1+)
 
+Control features dynamically and run A/B tests with Mixpanel Feature Flags. **Native mode only** (iOS/Android) in beta.
+
+#### Quick Start
+
+```js
+// Enable during initialization
+await mixpanel.init(false, {}, 'https://api.mixpanel.com', true, {
+  enabled: true,
+  context: { platform: 'mobile' }  // Optional targeting context
+});
+
+// Check if feature is enabled
+if (mixpanel.flags.areFlagsReady()) {
+  const showNewUI = mixpanel.flags.isEnabledSync('new-feature', false);
+  const buttonColor = mixpanel.flags.getVariantValueSync('button-color', 'blue');
+}
 ```
+
+#### Key Methods
+
+- `areFlagsReady()` - Check if flags are loaded
+- `isEnabledSync(name, fallback)` - Check if feature is enabled
+- `getVariantValueSync(name, fallback)` - Get variant value
+- `getVariantSync(name, fallback)` - Get full variant object with metadata
+
+All methods support async versions and snake_case aliases. See **[Feature Flags Quick Start Guide](FEATURE_FLAGS_QUICKSTART.md)** for complete documentation.
+
 ### Expo and React Native for Web support (3.0.2 and above)
-Starting from version 3.0.2, we have introduced support for Expo, React Native for Web, and other platforms utilizing React Native that do not support iOS and Android directly. 
-To enable this feature, 
-<br>Step 1: 
+
+Starting from version 3.0.2, we have introduced support for Expo, React Native for Web, and other platforms utilizing React Native that do not support iOS and Android directly.
+To enable this feature,
+<br>Step 1:
+
 ```
 npm install @react-native-async-storage/async-storage
 ```
+
 When JavaScript mode is enabled, Mixpanel utilizes [AsyncStorage](https://react-native-async-storage.github.io/async-storage/) to persist data. If you prefer not to use it, or if AsyncStorage is unavailable in your target environment, you can import or define a different storage class. However, it must follow a subset (see: [`MixpanelAsyncStorage`](index.d.ts)) of the same interface as [AsyncStorage](https://react-native-async-storage.github.io/async-storage/) The following example demonstrates how to use a custom storage solution:
 
 ```
 // Optional: if you do not want to use the default AsyncStorage
-const MyAsyncStorage = require("@my-org/<library-path>/AsyncStorage"); 
+const MyAsyncStorage = require("@my-org/<library-path>/AsyncStorage");
 const trackAutomaticEvents = false;
 const useNative = false;
 const mixpanel = new Mixpanel('YOUR_TOKEN', trackAutomaticEvents, useNative, MyAsyncStorage);
@@ -120,6 +167,7 @@ mixpanel.init();
 
 <br>Step 2:
 Initialize Mixpanel with an additional parameter, `useNative`, set to false.
+
 ```
 const trackAutomaticEvents = false;
 const useNative = false;
@@ -128,44 +176,46 @@ const mixpanel = new Mixpanel(
     trackAutomaticEvents,
     useNative
   );
-``` 
-This will activate JavaScript mode. 
-
+```
 
-👋 👋  Tell us about the Mixpanel developer experience! [https://www.mixpanel.com/devnps](https://www.mixpanel.com/devnps) 👍  👎
+This will activate JavaScript mode.
 
+👋 👋 Tell us about the Mixpanel developer experience! [https://www.mixpanel.com/devnps](https://www.mixpanel.com/devnps) 👍 👎
 
 ## FAQ
-**I want to stop tracking an event/event property in Mixpanel. Is that possible?**  
-Yes, in Lexicon, you can intercept and drop incoming events or properties. Mixpanel won’t store any new data for the event or property you select to drop.  [See this article for more information](https://help.mixpanel.com/hc/en-us/articles/360001307806#dropping-events-and-properties).
 
-**I have a test user I would like to opt out of tracking. How do I do that?**  
-Mixpanel’s client-side tracking library contains the  [optOutTracking()](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#optOutTracking)  method, which will set the user’s local opt-out state to “true” and will prevent data from being sent from a user’s device. More detailed instructions can be found in the section,  [Opting users out of tracking](https://developer.mixpanel.com/docs/react-native#opting-users-out-of-tracking).
+**I want to stop tracking an event/event property in Mixpanel. Is that possible?**
+Yes, in Lexicon, you can intercept and drop incoming events or properties. Mixpanel won’t store any new data for the event or property you select to drop. [See this article for more information](https://help.mixpanel.com/hc/en-us/articles/360001307806#dropping-events-and-properties).
+
+**I have a test user I would like to opt out of tracking. How do I do that?**
+Mixpanel’s client-side tracking library contains the [optOutTracking()](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#optOutTracking) method, which will set the user’s local opt-out state to “true” and will prevent data from being sent from a user’s device. More detailed instructions can be found in the section, [Opting users out of tracking](https://developer.mixpanel.com/docs/react-native#opting-users-out-of-tracking).
 
-**Why aren't my events showing up?**  
-First, make sure your test device has internet access. To preserve battery life and customer bandwidth, the Mixpanel library doesn't send the events you record immediately. Instead, it sends batches to the Mixpanel servers every 60 seconds while your application is running, as well as when the application transitions to the background. You can call  [flush()](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#flush)  manually if you want to force a flush at a particular moment.
+**Why aren't my events showing up?**
+First, make sure your test device has internet access. To preserve battery life and customer bandwidth, the Mixpanel library doesn't send the events you record immediately. Instead, it sends batches to the Mixpanel servers every 60 seconds while your application is running, as well as when the application transitions to the background. You can call [flush()](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#flush) manually if you want to force a flush at a particular moment.
 
 ```
 mixpanel.flush();
 ```
 
-If your events are still not showing up after 60 seconds, check if you have opted out of tracking. You can also enable Mixpanel debugging and logging, it allows you to see the debug output from the Mixpanel library. To enable it, call  [setLoggingEnabled](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#setLoggingEnabled) with true, then run your iOS project with Xcode or android project with Android Studio. The logs should be available in the console.
+If your events are still not showing up after 60 seconds, check if you have opted out of tracking. You can also enable Mixpanel debugging and logging, it allows you to see the debug output from the Mixpanel library. To enable it, call [setLoggingEnabled](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#setLoggingEnabled) with true, then run your iOS project with Xcode or android project with Android Studio. The logs should be available in the console.
 
 ```
 mixpanel.setLoggingEnabled(true);
 ```
 
-**Starting with iOS 14.5, do I need to request the user’s permission through the AppTrackingTransparency framework to use Mixpanel?**  
+**Starting with iOS 14.5, do I need to request the user’s permission through the AppTrackingTransparency framework to use Mixpanel?**
 No, Mixpanel does not use IDFA so it does not require user permission through the AppTrackingTransparency(ATT) framework.
 
-**If I use Mixpanel, how do I answer app privacy questions for the App Store?**  
-Please refer to our  [Apple App Developer Privacy Guidance](https://mixpanel.com/legal/app-store-privacy-details/)
-
+**If I use Mixpanel, how do I answer app privacy questions for the App Store?**
+Please refer to our [Apple App Developer Privacy Guidance](https://mixpanel.com/legal/app-store-privacy-details/)
 
 ## I want to know more!
 
 No worries, here are some links that you will find useful:
-* **[Sample apps](https://github.com/mixpanel/mixpanel-react-native/tree/master/Samples)**
-* **[Full API Reference](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html)**
+
+- **[Sample apps](https://github.com/mixpanel/mixpanel-react-native/tree/master/Samples)**
+- **[Full API Reference](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html)**
+
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/mixpanel/mixpanel-react-native)
 
 Have any questions? Reach out to Mixpanel [Support](https://help.mixpanel.com/hc/en-us/requests/new) to speak to someone smart, quickly.

package/Samples/MixpanelExpo/.yalc/mixpanel-react-native/android/build.gradle

@@ -41,5 +41,5 @@ repositories {
 
 dependencies {
     implementation 'com.facebook.react:react-native:+'
-    implementation 'com.mixpanel.android:mixpanel-android:8.1.0'
+    implementation 'com.mixpanel.android:mixpanel-android:8.2.4'
 }

package/Samples/MixpanelExpo/.yalc/mixpanel-react-native/android/src/main/java/com/mixpanel/reactnative/MixpanelReactNativeModule.java

@@ -1,6 +1,9 @@
 package com.mixpanel.reactnative;
 
 import com.mixpanel.android.mpmetrics.MixpanelAPI;
+import com.mixpanel.android.mpmetrics.MixpanelOptions;
+import com.mixpanel.android.mpmetrics.MixpanelFlagVariant;
+import com.mixpanel.android.mpmetrics.FlagCompletionCallback;
 
 import com.facebook.react.bridge.Promise;
 import com.facebook.react.bridge.ReactApplicationContext;
@@ -9,6 +12,10 @@ import com.facebook.react.bridge.ReactMethod;
 import com.facebook.react.bridge.ReadableArray;
 import com.facebook.react.bridge.ReadableMap;
 import com.facebook.react.bridge.Dynamic;
+import com.facebook.react.bridge.WritableMap;
+import com.facebook.react.bridge.WritableNativeMap;
+import com.facebook.react.bridge.WritableArray;
+import com.facebook.react.bridge.Callback;
 
 import org.json.JSONArray;
 import org.json.JSONException;
@@ -33,10 +40,35 @@ public class MixpanelReactNativeModule extends ReactContextBaseJavaModule {
 
 
     @ReactMethod
-    public void initialize(String token, boolean trackAutomaticEvents, boolean optOutTrackingDefault, ReadableMap metadata, String serverURL, boolean useGzipCompression, Promise promise) throws JSONException {
+    public void initialize(String token, boolean trackAutomaticEvents, boolean optOutTrackingDefault, ReadableMap metadata, String serverURL, boolean useGzipCompression, ReadableMap featureFlagsOptions, Promise promise) throws JSONException {
         JSONObject mixpanelProperties = ReactNativeHelper.reactToJSON(metadata);
         AutomaticProperties.setAutomaticProperties(mixpanelProperties);
-        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, optOutTrackingDefault, mixpanelProperties, null, trackAutomaticEvents);
+
+        // Handle feature flags options
+        boolean featureFlagsEnabled = false;
+        JSONObject featureFlagsContext = null;
+
+        if (featureFlagsOptions != null && featureFlagsOptions.hasKey("enabled")) {
+            featureFlagsEnabled = featureFlagsOptions.getBoolean("enabled");
+
+            if (featureFlagsOptions.hasKey("context")) {
+                featureFlagsContext = ReactNativeHelper.reactToJSON(featureFlagsOptions.getMap("context"));
+            }
+        }
+
+        // Create Mixpanel instance with feature flags configuration
+        MixpanelOptions.Builder optionsBuilder = new MixpanelOptions.Builder()
+            .optOutTrackingDefault(optOutTrackingDefault)
+            .superProperties(mixpanelProperties)
+            .featureFlagsEnabled(featureFlagsEnabled);
+
+        if (featureFlagsContext != null) {
+            optionsBuilder.featureFlagsContext(featureFlagsContext);
+        }
+
+        MixpanelOptions options = optionsBuilder.build();
+
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, trackAutomaticEvents, options);
         instance.setServerURL(serverURL);
         if (useGzipCompression) {
             instance.setShouldGzipRequestPayload(true);
@@ -602,4 +634,242 @@ public class MixpanelReactNativeModule extends ReactContextBaseJavaModule {
             promise.resolve(null);
         }
     }
+
+    // Feature Flags Methods
+
+    @ReactMethod
+    public void loadFlags(final String token, Promise promise) {
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+        if (instance == null) {
+            promise.reject("Instance Error", "Failed to get Mixpanel instance");
+            return;
+        }
+        synchronized (instance) {
+            instance.getFlags().loadFlags();
+            promise.resolve(null);
+        }
+    }
+
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    public boolean areFlagsReadySync(final String token) {
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+        if (instance == null) {
+            return false;
+        }
+        synchronized (instance) {
+            return instance.getFlags().areFlagsReady();
+        }
+    }
+
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    public WritableMap getVariantSync(final String token, String featureName, ReadableMap fallback) {
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+        if (instance == null) {
+            return convertVariantToMap(fallback);
+        }
+
+        synchronized (instance) {
+            MixpanelFlagVariant fallbackVariant = convertMapToVariant(fallback);
+            MixpanelFlagVariant variant = instance.getFlags().getVariantSync(featureName, fallbackVariant);
+            return convertVariantToWritableMap(variant);
+        }
+    }
+
+    // Note: For getVariantValueSync, we'll return the full variant and extract value in JS
+    // React Native doesn't support returning Dynamic types from synchronous methods
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    public WritableMap getVariantValueSync(final String token, String featureName, Dynamic fallbackValue) {
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+
+        WritableMap result = new WritableNativeMap();
+        if (instance == null) {
+            result.putString("type", "fallback");
+            // We'll handle the conversion in JavaScript
+            return result;
+        }
+
+        synchronized (instance) {
+            Object value = instance.getFlags().getVariantValueSync(featureName, ReactNativeHelper.dynamicToObject(fallbackValue));
+            result.putString("type", "value");
+
+            // Convert value to appropriate type
+            if (value == null) {
+                result.putNull("value");
+            } else if (value instanceof String) {
+                result.putString("value", (String) value);
+            } else if (value instanceof Boolean) {
+                result.putBoolean("value", (Boolean) value);
+            } else if (value instanceof Integer) {
+                result.putInt("value", (Integer) value);
+            } else if (value instanceof Double) {
+                result.putDouble("value", (Double) value);
+            } else if (value instanceof Float) {
+                result.putDouble("value", ((Float) value).doubleValue());
+            } else if (value instanceof Long) {
+                result.putDouble("value", ((Long) value).doubleValue());
+            } else {
+                result.putString("value", value.toString());
+            }
+
+            return result;
+        }
+    }
+
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    public boolean isEnabledSync(final String token, String featureName, boolean fallbackValue) {
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+        if (instance == null) {
+            return fallbackValue;
+        }
+
+        synchronized (instance) {
+            return instance.getFlags().isEnabledSync(featureName, fallbackValue);
+        }
+    }
+
+    @ReactMethod
+    public void getVariant(final String token, String featureName, ReadableMap fallback, final Promise promise) {
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+        if (instance == null) {
+            promise.resolve(convertVariantToMap(fallback));
+            return;
+        }
+
+        synchronized (instance) {
+            MixpanelFlagVariant fallbackVariant = convertMapToVariant(fallback);
+            instance.getFlags().getVariant(featureName, fallbackVariant, new FlagCompletionCallback<MixpanelFlagVariant>() {
+                @Override
+                public void onComplete(MixpanelFlagVariant variant) {
+                    promise.resolve(convertVariantToWritableMap(variant));
+                }
+            });
+        }
+    }
+
+    @ReactMethod
+    public void getVariantValue(final String token, String featureName, Dynamic fallbackValue, final Promise promise) {
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+        if (instance == null) {
+            promise.resolve(fallbackValue);
+            return;
+        }
+
+        synchronized (instance) {
+            Object fallbackObj = ReactNativeHelper.dynamicToObject(fallbackValue);
+            instance.getFlags().getVariantValue(featureName, fallbackObj, new FlagCompletionCallback<Object>() {
+                @Override
+                public void onComplete(Object value) {
+                    // Convert the value back to a format React Native can handle
+                    if (value == null) {
+                        promise.resolve(null);
+                    } else if (value instanceof String) {
+                        promise.resolve((String) value);
+                    } else if (value instanceof Boolean) {
+                        promise.resolve((Boolean) value);
+                    } else if (value instanceof Number) {
+                        promise.resolve(((Number) value).doubleValue());
+                    } else if (value instanceof JSONObject) {
+                        try {
+                            WritableMap map = ReactNativeHelper.convertJsonToMap((JSONObject) value);
+                            promise.resolve(map);
+                        } catch (Exception e) {
+                            promise.resolve(value.toString());
+                        }
+                    } else if (value instanceof JSONArray) {
+                        try {
+                            WritableArray array = ReactNativeHelper.convertJsonToArray((JSONArray) value);
+                            promise.resolve(array);
+                        } catch (Exception e) {
+                            promise.resolve(value.toString());
+                        }
+                    } else {
+                        promise.resolve(value.toString());
+                    }
+                }
+            });
+        }
+    }
+
+    @ReactMethod
+    public void isEnabled(final String token, String featureName, boolean fallbackValue, final Promise promise) {
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+        if (instance == null) {
+            promise.resolve(fallbackValue);
+            return;
+        }
+
+        synchronized (instance) {
+            instance.getFlags().isEnabled(featureName, fallbackValue, new FlagCompletionCallback<Boolean>() {
+                @Override
+                public void onComplete(Boolean isEnabled) {
+                    promise.resolve(isEnabled);
+                }
+            });
+        }
+    }
+
+    // Helper methods for variant conversion
+    private MixpanelFlagVariant convertMapToVariant(ReadableMap map) {
+        if (map == null) {
+            return new MixpanelFlagVariant("", null);
+        }
+
+        String key = map.hasKey("key") ? map.getString("key") : "";
+        Object value = map.hasKey("value") ? ReactNativeHelper.dynamicToObject(map.getDynamic("value")) : null;
+        String experimentID = map.hasKey("experimentID") ? map.getString("experimentID") : null;
+        Boolean isExperimentActive = map.hasKey("isExperimentActive") ? map.getBoolean("isExperimentActive") : null;
+        Boolean isQATester = map.hasKey("isQATester") ? map.getBoolean("isQATester") : null;
+
+        // Create variant with all properties using the full constructor
+        return new MixpanelFlagVariant(key, value, experimentID, isExperimentActive, isQATester);
+    }
+
+    private WritableMap convertVariantToMap(ReadableMap source) {
+        WritableMap map = new WritableNativeMap();
+        if (source != null) {
+            map.merge(source);
+        }
+        return map;
+    }
+
+    private WritableMap convertVariantToWritableMap(MixpanelFlagVariant variant) {
+        WritableMap map = new WritableNativeMap();
+
+        if (variant != null) {
+            map.putString("key", variant.key);
+
+            Object value = variant.value;
+            if (value == null) {
+                map.putNull("value");
+            } else if (value instanceof String) {
+                map.putString("value", (String) value);
+            } else if (value instanceof Boolean) {
+                map.putBoolean("value", (Boolean) value);
+            } else if (value instanceof Integer) {
+                map.putInt("value", (Integer) value);
+            } else if (value instanceof Double) {
+                map.putDouble("value", (Double) value);
+            } else if (value instanceof Float) {
+                map.putDouble("value", ((Float) value).doubleValue());
+            } else if (value instanceof Long) {
+                map.putDouble("value", ((Long) value).doubleValue());
+            } else {
+                // For complex objects, convert to string
+                map.putString("value", value.toString());
+            }
+
+            // Add optional fields if they exist
+            if (variant.experimentID != null) {
+                map.putString("experimentID", variant.experimentID);
+            }
+            if (variant.isExperimentActive != null) {
+                map.putBoolean("isExperimentActive", variant.isExperimentActive);
+            }
+            if (variant.isQATester != null) {
+                map.putBoolean("isQATester", variant.isQATester);
+            }
+        }
+
+        return map;
+    }
 }

package/Samples/MixpanelExpo/.yalc/mixpanel-react-native/index.d.ts

@@ -7,7 +7,69 @@ export type MixpanelAsyncStorage = {
   removeItem(key: string): Promise<void>;
 };
 
+export interface MixpanelFlagVariant {
+  key: string;
+  value: any;
+  experiment_id?: string | number;  // Updated to match mixpanel-js format
+  is_experiment_active?: boolean;    // Updated to match mixpanel-js format
+  is_qa_tester?: boolean;            // Updated to match mixpanel-js format
+}
+
+export interface FeatureFlagsOptions {
+  enabled?: boolean;
+  context?: {
+    [key: string]: any;
+    custom_properties?: {
+      [key: string]: any;
+    };
+  };
+}
+
+export interface UpdateContextOptions {
+  replace?: boolean;
+}
+
+export interface Flags {
+  // Synchronous methods
+  loadFlags(): Promise<void>;
+  areFlagsReady(): boolean;
+  getVariantSync(featureName: string, fallback: MixpanelFlagVariant): MixpanelFlagVariant;
+  getVariantValueSync(featureName: string, fallbackValue: any): any;
+  isEnabledSync(featureName: string, fallbackValue?: boolean): boolean;
+
+  // Asynchronous methods with overloads for callback and Promise patterns
+  getVariant(featureName: string, fallback: MixpanelFlagVariant): Promise<MixpanelFlagVariant>;
+  getVariant(featureName: string, fallback: MixpanelFlagVariant, callback: (result: MixpanelFlagVariant) => void): void;
+
+  getVariantValue(featureName: string, fallbackValue: any): Promise<any>;
+  getVariantValue(featureName: string, fallbackValue: any, callback: (value: any) => void): void;
+
+  isEnabled(featureName: string, fallbackValue?: boolean): Promise<boolean>;
+  isEnabled(featureName: string, fallbackValue: boolean, callback: (isEnabled: boolean) => void): void;
+
+  // Context management (NEW - aligned with mixpanel-js)
+  // NOTE: Only available in JavaScript mode (Expo/React Native Web)
+  // In native mode, throws an error - context must be set during initialization
+  updateContext(newContext: MixpanelProperties, options?: UpdateContextOptions): Promise<void>;
+
+  // snake_case aliases (NEW - aligned with mixpanel-js)
+  are_flags_ready(): boolean;
+  get_variant(featureName: string, fallback: MixpanelFlagVariant): Promise<MixpanelFlagVariant>;
+  get_variant(featureName: string, fallback: MixpanelFlagVariant, callback: (result: MixpanelFlagVariant) => void): void;
+  get_variant_sync(featureName: string, fallback: MixpanelFlagVariant): MixpanelFlagVariant;
+  get_variant_value(featureName: string, fallbackValue: any): Promise<any>;
+  get_variant_value(featureName: string, fallbackValue: any, callback: (value: any) => void): void;
+  get_variant_value_sync(featureName: string, fallbackValue: any): any;
+  is_enabled(featureName: string, fallbackValue?: boolean): Promise<boolean>;
+  is_enabled(featureName: string, fallbackValue: boolean, callback: (isEnabled: boolean) => void): void;
+  is_enabled_sync(featureName: string, fallbackValue?: boolean): boolean;
+  // NOTE: Only available in JavaScript mode (Expo/React Native Web)
+  update_context(newContext: MixpanelProperties, options?: UpdateContextOptions): Promise<void>;
+}
+
 export class Mixpanel {
+  readonly flags: Flags;
+
   constructor(token: string, trackAutoMaticEvents: boolean);
   constructor(token: string, trackAutoMaticEvents: boolean, useNative: true);
   constructor(
@@ -24,7 +86,9 @@ export class Mixpanel {
   init(
     optOutTrackingDefault?: boolean,
     superProperties?: MixpanelProperties,
-    serverURL?: String
+    serverURL?: string,
+    useGzipCompression?: boolean,
+    featureFlagsOptions?: FeatureFlagsOptions
   ): Promise<void>;
   setServerURL(serverURL: string): void;
   setLoggingEnabled(loggingEnabled: boolean): void;