mixpanel-react-native 3.2.0-beta.1 → 3.2.0-beta.2

package/FEATURE_FLAGS_QUICKSTART.md

@@ -0,0 +1,348 @@
+# Feature Flags Quick Start Guide (Beta)
+
+> **Beta Version:** `3.2.0-beta.1`
+> **Native Mode Only:** This beta release supports iOS and Android native implementations. JavaScript mode (Expo/React Native Web) support coming in future release.
+
+## Installation
+
+Install the beta version:
+
+```bash
+npm install mixpanel-react-native@3.2.0-beta.1
+```
+
+For iOS, update native dependencies:
+
+```bash
+cd ios && pod install
+```
+
+## Basic Setup
+
+### 1. Initialize with Feature Flags Enabled
+
+```javascript
+import { Mixpanel } from 'mixpanel-react-native';
+
+const mixpanel = new Mixpanel('YOUR_TOKEN');
+
+// Enable Feature Flags during initialization
+await mixpanel.init(
+  false,                    // optOutTrackingDefault
+  {},                       // superProperties
+  'https://api.mixpanel.com', // serverURL
+  true,                     // useGzipCompression
+  {
+    enabled: true,          // Enable Feature Flags
+    context: {              // Optional: Add targeting context
+      platform: 'mobile',
+      app_version: '2.1.0'
+    }
+  }
+);
+```
+
+### 2. Check Flag Availability
+
+Before accessing flags, verify they're loaded:
+
+```javascript
+if (mixpanel.flags.areFlagsReady()) {
+  // Flags are ready to use
+  console.log('Feature flags loaded!');
+}
+```
+
+## Using Feature Flags
+
+### Synchronous API (Recommended for UI)
+
+Use sync methods when flags are ready (e.g., in render methods):
+
+```javascript
+// Check if feature is enabled
+const showNewUI = mixpanel.flags.isEnabledSync('new-checkout-flow', false);
+
+// Get variant value directly
+const buttonColor = mixpanel.flags.getVariantValueSync('button-color', 'blue');
+
+// Get full variant object with metadata
+const variant = mixpanel.flags.getVariantSync('pricing-tier', {
+  key: 'control',
+  value: 'standard'
+});
+
+console.log(`Variant: ${variant.key}, Value: ${variant.value}`);
+if (variant.experiment_id) {
+  console.log(`Part of experiment: ${variant.experiment_id}`);
+}
+```
+
+### Asynchronous API (Promise Pattern)
+
+Use async methods for event handlers or initialization:
+
+```javascript
+// Promise pattern
+const variant = await mixpanel.flags.getVariant('checkout-flow', {
+  key: 'control',
+  value: 'standard'
+});
+
+const enabled = await mixpanel.flags.isEnabled('dark-mode', false);
+
+const colorValue = await mixpanel.flags.getVariantValue('theme-color', '#0000FF');
+```
+
+### Asynchronous API (Callback Pattern)
+
+Alternative callback style for compatibility:
+
+```javascript
+// Callback pattern
+mixpanel.flags.getVariant('feature-name', { key: 'control', value: 'off' }, (variant) => {
+  console.log(`Feature variant: ${variant.key}`);
+});
+
+mixpanel.flags.isEnabled('new-feature', false, (isEnabled) => {
+  if (isEnabled) {
+    // Show new feature
+  }
+});
+```
+
+## Real-World Examples
+
+### Example 1: Feature Toggle
+
+```javascript
+const NewCheckoutButton = () => {
+  const [showNewCheckout, setShowNewCheckout] = useState(false);
+
+  useEffect(() => {
+    // Load flags on mount
+    if (mixpanel.flags.areFlagsReady()) {
+      const enabled = mixpanel.flags.isEnabledSync('new-checkout', false);
+      setShowNewCheckout(enabled);
+    }
+  }, []);
+
+  return showNewCheckout ? <NewCheckout /> : <LegacyCheckout />;
+};
+```
+
+### Example 2: A/B Test with Variants
+
+```javascript
+const ProductCard = ({ product }) => {
+  // Get button color variant (A/B test)
+  const buttonColor = mixpanel.flags.areFlagsReady()
+    ? mixpanel.flags.getVariantValueSync('button-color', 'blue')
+    : 'blue';
+
+  // Get pricing display variant
+  const pricingVariant = mixpanel.flags.areFlagsReady()
+    ? mixpanel.flags.getVariantSync('pricing-display', {
+        key: 'control',
+        value: 'standard'
+      })
+    : { key: 'control', value: 'standard' };
+
+  return (
+    <View>
+      <Text>{product.name}</Text>
+      {pricingVariant.value === 'bold' ? (
+        <Text style={styles.boldPrice}>${product.price}</Text>
+      ) : (
+        <Text>${product.price}</Text>
+      )}
+      <Button
+        title="Add to Cart"
+        color={buttonColor}
+        onPress={handleAddToCart}
+      />
+    </View>
+  );
+};
+```
+
+### Example 3: Gradual Rollout with Fallback
+
+```javascript
+const App = () => {
+  const [uiVersion, setUiVersion] = useState('v1');
+
+  useEffect(() => {
+    const loadFlags = async () => {
+      try {
+        // Manually trigger flag load
+        await mixpanel.flags.loadFlags();
+
+        // Check which UI version to show
+        const variant = mixpanel.flags.getVariantSync('ui-redesign', {
+          key: 'control',
+          value: 'v1'
+        });
+
+        setUiVersion(variant.value);
+
+        // Track if user is in experiment
+        if (variant.experiment_id) {
+          console.log(`User in experiment: ${variant.experiment_id}`);
+        }
+      } catch (error) {
+        console.error('Failed to load flags:', error);
+        // Fallback to default
+      }
+    };
+
+    loadFlags();
+  }, []);
+
+  return uiVersion === 'v2' ? <NewUI /> : <LegacyUI />;
+};
+```
+
+### Example 4: Targeting with Context
+
+```javascript
+// Set user context for targeting
+await mixpanel.init(
+  false,
+  {},
+  'https://api.mixpanel.com',
+  true,
+  {
+    enabled: true,
+    context: {
+      user_tier: 'premium',
+      device_type: Platform.OS,
+      app_version: '2.1.0',
+      custom_properties: {
+        beta_tester: true,
+        region: 'US'
+      }
+    }
+  }
+);
+
+// Flags will be evaluated based on context
+const hasAccess = mixpanel.flags.isEnabledSync('premium-feature', false);
+```
+
+## API Reference
+
+### Methods
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `areFlagsReady()` | Sync | Returns `true` if flags are loaded |
+| `loadFlags()` | Async | Manually fetch flags from server |
+| `isEnabledSync(name, fallback)` | Sync | Check if feature is enabled |
+| `isEnabled(name, fallback)` | Async | Async version of isEnabledSync |
+| `getVariantValueSync(name, fallback)` | Sync | Get variant value only |
+| `getVariantValue(name, fallback)` | Async | Async version of getVariantValueSync |
+| `getVariantSync(name, fallback)` | Sync | Get full variant object |
+| `getVariant(name, fallback)` | Async | Async version of getVariantSync |
+
+### Snake Case Aliases
+
+All methods have snake_case aliases for consistency with mixpanel-js:
+
+```javascript
+// These are equivalent
+mixpanel.flags.areFlagsReady()
+mixpanel.flags.are_flags_ready()
+
+mixpanel.flags.getVariantSync('feature', fallback)
+mixpanel.flags.get_variant_sync('feature', fallback)
+```
+
+## Automatic Experiment Tracking
+
+When a user is evaluated for a flag that's part of an A/B test, Mixpanel automatically tracks an `$experiment_started` event. No additional code required!
+
+## Important Notes
+
+### Platform Support
+
+- ✅ **iOS**: Full support via native Swift SDK
+- ✅ **Android**: Full support via native Android SDK
+- ❌ **Expo/React Native Web**: Not supported in this beta (coming soon)
+
+### Fallback Values
+
+Always provide fallback values for graceful degradation:
+
+```javascript
+// Good - provides fallback
+const color = mixpanel.flags.getVariantValueSync('color', 'blue');
+
+// Bad - could return undefined if flag not found
+const color = mixpanel.flags.getVariantValueSync('color');
+```
+
+### Performance
+
+- Flags are lazy-loaded on first access
+- Sync methods are preferred for UI rendering (no async overhead)
+- Check `areFlagsReady()` before using sync methods
+
+### Error Handling
+
+Flags fail gracefully and return fallback values:
+
+```javascript
+try {
+  await mixpanel.flags.loadFlags();
+} catch (error) {
+  console.error('Flag loading failed:', error);
+  // App continues with fallback values
+}
+```
+
+## Troubleshooting
+
+### Flags Not Loading
+
+1. Verify Feature Flags are enabled in your Mixpanel project
+2. Check initialization includes `featureFlagsOptions: { enabled: true }`
+3. Enable logging: `mixpanel.setLoggingEnabled(true)`
+4. Verify network connectivity to Mixpanel API
+
+### Native Module Not Found
+
+This beta requires native modules. If you see "Native module not found":
+
+1. Run `cd ios && pod install` (iOS)
+2. Rebuild the app completely
+3. Verify you're not using Expo Go (use dev client or eject)
+
+### Getting Fallback Values
+
+If flags always return fallbacks:
+
+1. Check `mixpanel.flags.areFlagsReady()` returns `true`
+2. Verify flag names match exactly (case-sensitive)
+3. Confirm flags are published in Mixpanel dashboard
+4. Check context targeting rules
+
+## Feedback & Issues
+
+This is a beta release. Please report issues at:
+https://github.com/mixpanel/mixpanel-react-native/issues
+
+Reference PR #331 for technical details:
+https://github.com/mixpanel/mixpanel-react-native/pull/331
+
+## What's Next
+
+Coming in future releases:
+
+- JavaScript mode support (Expo/React Native Web)
+- Runtime context updates via `updateContext()`
+- Performance optimizations
+
+---
+
+**Questions?** Visit [Mixpanel Documentation](https://mixpanel.com) or reach out to support.

package/README.md

@@ -115,6 +115,35 @@ const SampleApp = () => {
 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.

package/index.js

@@ -63,10 +63,27 @@ export class Mixpanel {
 
   /**
    * Returns the Flags instance for feature flags operations.
-   * This property is lazy-loaded to avoid unnecessary initialization.
    *
-   * NOTE: Feature flags are only available in native mode.
-   * JavaScript mode is not yet supported.
+   * <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() {
     // Short circuit for JavaScript mode - flags not ready for public use
@@ -86,13 +103,50 @@ export class Mixpanel {
   }
 
   /**
-   * Initializes Mixpanel
-   *
-   * @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.
-   * @param {object} featureFlagsOptions Optional Feature flags configuration including enabled flag and context
+   * 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,

package/javascript/mixpanel-flags.js

@@ -1,8 +1,68 @@
 import { MixpanelFlagsJS } from './mixpanel-flags-js';
 
 /**
- * Flags class for managing Feature Flags functionality
- * This class handles both native and JavaScript fallback implementations
+ * Core class for using Mixpanel Feature Flags.
+ *
+ * <p>The Flags class provides access to Mixpanel's Feature Flags functionality, enabling
+ * dynamic feature control, A/B testing, and personalized user experiences. Feature flags
+ * allow you to remotely configure your app's features without deploying new code.
+ *
+ * <p>This class is accessed through the {@link Mixpanel#flags} property and is lazy-loaded
+ * to minimize performance impact until feature flags are actually used.
+ *
+ * <p><b>Platform Support:</b>
+ * <ul>
+ * <li><b>Native Mode (iOS/Android):</b> Fully supported with automatic experiment tracking</li>
+ * <li><b>JavaScript Mode (Expo/React Native Web):</b> Planned for future release</li>
+ * </ul>
+ *
+ * <p><b>Key Concepts:</b>
+ * <ul>
+ * <li><b>Feature Name:</b> The unique identifier for your feature flag (e.g., "new-checkout")</li>
+ * <li><b>Variant:</b> An object containing both a key and value representing the feature configuration</li>
+ * <li><b>Variant Key:</b> The identifier for the specific variation (e.g., "control", "treatment")</li>
+ * <li><b>Variant Value:</b> The actual configuration value (can be any JSON-serializable type)</li>
+ * <li><b>Fallback:</b> Default value returned when a flag is not available or not loaded</li>
+ * </ul>
+ *
+ * <p><b>Automatic Experiment Tracking:</b> When a feature flag is evaluated for the first time,
+ * Mixpanel automatically tracks a "$experiment_started" event with relevant metadata.
+ *
+ * @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' }
+ * });
+ *
+ * @example
+ * // Synchronous access (when flags are ready)
+ * if (mixpanel.flags.areFlagsReady()) {
+ *   const isEnabled = mixpanel.flags.isEnabledSync('new-feature', false);
+ *   const color = mixpanel.flags.getVariantValueSync('button-color', 'blue');
+ *   const variant = mixpanel.flags.getVariantSync('checkout-flow', {
+ *     key: 'control',
+ *     value: 'standard'
+ *   });
+ * }
+ *
+ * @example
+ * // Asynchronous access with Promise pattern
+ * const variant = await mixpanel.flags.getVariant('pricing-test', {
+ *   key: 'control',
+ *   value: { price: 9.99, currency: 'USD' }
+ * });
+ *
+ * @example
+ * // Asynchronous access with callback pattern
+ * mixpanel.flags.isEnabled('beta-features', false, (isEnabled) => {
+ *   if (isEnabled) {
+ *     // Enable beta features
+ *   }
+ * });
+ *
+ * @see Mixpanel#flags
  */
 export class Flags {
   constructor(token, mixpanelImpl, storage) {
@@ -18,8 +78,26 @@ export class Flags {
   }
 
   /**
-   * Manually trigger a fetch of feature flags from the Mixpanel servers.
-   * This is usually automatic but can be called manually if needed.
+   * Manually fetch feature flags from the Mixpanel servers.
+   *
+   * <p>Feature flags are automatically loaded during initialization when feature flags are enabled.
+   * This method allows you to manually trigger a refresh of the flags, which is useful when:
+   * <ul>
+   * <li>You want to reload flags after a user property change</li>
+   * <li>You need to ensure you have the latest flag configuration</li>
+   * <li>Initial automatic load failed and you want to retry</li>
+   * </ul>
+   *
+   * <p>After successfully loading flags, {@link areFlagsReady} will return true and synchronous
+   * methods can be used to access flag values.
+   *
+   * @returns {Promise<void>} A promise that resolves when flags have been fetched and loaded
+   * @throws {Error} if feature flags are not initialized
+   *
+   * @example
+   * // Manually reload flags after user identification
+   * await mixpanel.identify('user123');
+   * await mixpanel.flags.loadFlags();
    */
   async loadFlags() {
     if (this.isNativeMode) {
@@ -31,8 +109,31 @@ export class Flags {
   }
 
   /**
-   * Check if feature flags have been fetched and are ready to use.
-   * @returns {boolean} True if flags are ready, false otherwise
+   * Check if feature flags have been fetched from the server and are ready to use.
+   *
+   * <p>This method returns true after feature flags have been successfully loaded via {@link loadFlags}
+   * or during initialization. When flags are ready, you can safely use the synchronous methods
+   * ({@link getVariantSync}, {@link getVariantValueSync}, {@link isEnabledSync}) without waiting.
+   *
+   * <p>It's recommended to check this before using synchronous methods to ensure you're not
+   * getting fallback values due to flags not being loaded yet.
+   *
+   * @returns {boolean} true if flags have been loaded and are ready to use, false otherwise
+   *
+   * @example
+   * // Check before using synchronous methods
+   * if (mixpanel.flags.areFlagsReady()) {
+   *   const isEnabled = mixpanel.flags.isEnabledSync('new-feature', false);
+   * } else {
+   *   console.log('Flags not ready yet, using fallback');
+   * }
+   *
+   * @example
+   * // Wait for flags to be ready
+   * await mixpanel.flags.loadFlags();
+   * if (mixpanel.flags.areFlagsReady()) {
+   *   // Now safe to use sync methods
+   * }
    */
   areFlagsReady() {
     if (this.isNativeMode) {
@@ -44,10 +145,51 @@ export class Flags {
   }
 
   /**
-   * Get a feature flag variant synchronously. Only works when flags are ready.
-   * @param {string} featureName - Name of the feature flag
-   * @param {object} fallback - Fallback variant if flag is not available
-   * @returns {object} The flag variant with key and value properties
+   * Get a feature flag variant synchronously.
+   *
+   * <p>Returns the complete variant object for a feature flag, including both the variant key
+   * (e.g., "control", "treatment") and the variant value (the actual configuration data).
+   *
+   * <p><b>Important:</b> This is a synchronous method that only works when flags are ready.
+   * Always check {@link areFlagsReady} first, or use the asynchronous {@link getVariant} method instead.
+   *
+   * <p>When a flag is evaluated for the first time, Mixpanel automatically tracks a
+   * "$experiment_started" event with relevant experiment metadata.
+   *
+   * @param {string} featureName The unique identifier for the feature flag
+   * @param {object} fallback The fallback variant object to return if the flag is not available.
+   *     Must include both 'key' and 'value' properties.
+   * @returns {object} The flag variant object with the following structure:
+   *     - key: {string} The variant key (e.g., "control", "treatment")
+   *     - value: {any} The variant value (can be any JSON-serializable type)
+   *     - experiment_id: {string|number} (optional) The experiment ID if this is an experiment
+   *     - is_experiment_active: {boolean} (optional) Whether the experiment is currently active
+   *
+   * @example
+   * // Get a checkout flow variant
+   * if (mixpanel.flags.areFlagsReady()) {
+   *   const variant = mixpanel.flags.getVariantSync('checkout-flow', {
+   *     key: 'control',
+   *     value: 'standard'
+   *   });
+   *   console.log(`Using variant: ${variant.key}`);
+   *   console.log(`Configuration: ${JSON.stringify(variant.value)}`);
+   * }
+   *
+   * @example
+   * // Get a complex configuration variant
+   * const defaultConfig = {
+   *   key: 'default',
+   *   value: {
+   *     theme: 'light',
+   *     layout: 'grid',
+   *     itemsPerPage: 20
+   *   }
+   * };
+   * const config = mixpanel.flags.getVariantSync('ui-config', defaultConfig);
+   *
+   * @see getVariant for asynchronous access
+   * @see getVariantValueSync to get only the value (not the full variant object)
    */
   getVariantSync(featureName, fallback) {
     if (!this.areFlagsReady()) {
@@ -63,10 +205,45 @@ export class Flags {
   }
 
   /**
-   * Get a feature flag variant value synchronously. Only works when flags are ready.
-   * @param {string} featureName - Name of the feature flag
-   * @param {any} fallbackValue - Fallback value if flag is not available
-   * @returns {any} The flag value
+   * Get a feature flag variant value synchronously.
+   *
+   * <p>Returns only the value portion of a feature flag variant, without the variant key or metadata.
+   * This is useful when you only care about the configuration data, not which variant was selected.
+   *
+   * <p><b>Important:</b> This is a synchronous method that only works when flags are ready.
+   * Always check {@link areFlagsReady} first, or use the asynchronous {@link getVariantValue} method instead.
+   *
+   * <p>When a flag is evaluated for the first time, Mixpanel automatically tracks a
+   * "$experiment_started" event with relevant experiment metadata.
+   *
+   * @param {string} featureName The unique identifier for the feature flag
+   * @param {any} fallbackValue The fallback value to return if the flag is not available.
+   *     Can be any JSON-serializable type (string, number, boolean, object, array, etc.)
+   * @returns {any} The flag's value, or the fallback if the flag is not available.
+   *     The return type matches the type of value configured in your Mixpanel project.
+   *
+   * @example
+   * // Get a simple string value
+   * if (mixpanel.flags.areFlagsReady()) {
+   *   const buttonColor = mixpanel.flags.getVariantValueSync('button-color', 'blue');
+   *   applyButtonColor(buttonColor);
+   * }
+   *
+   * @example
+   * // Get a complex object value
+   * const defaultPricing = { price: 9.99, currency: 'USD', trial_days: 7 };
+   * const pricing = mixpanel.flags.getVariantValueSync('pricing-config', defaultPricing);
+   * console.log(`Price: ${pricing.price} ${pricing.currency}`);
+   *
+   * @example
+   * // Get a boolean value
+   * const showPromo = mixpanel.flags.getVariantValueSync('show-promo', false);
+   * if (showPromo) {
+   *   displayPromotionalBanner();
+   * }
+   *
+   * @see getVariantValue for asynchronous access
+   * @see getVariantSync to get the full variant object including key and metadata
    */
   getVariantValueSync(featureName, fallbackValue) {
     if (!this.areFlagsReady()) {
@@ -89,10 +266,39 @@ export class Flags {
   }
 
   /**
-   * Check if a feature flag is enabled synchronously. Only works when flags are ready.
-   * @param {string} featureName - Name of the feature flag
-   * @param {boolean} fallbackValue - Fallback value if flag is not available
-   * @returns {boolean} True if enabled, false otherwise
+   * Check if a feature flag is enabled synchronously.
+   *
+   * <p>This is a convenience method for boolean feature flags. It checks if a feature is enabled
+   * by evaluating the variant value as a boolean. A feature is considered "enabled" when its
+   * variant value evaluates to true.
+   *
+   * <p><b>Important:</b> This is a synchronous method that only works when flags are ready.
+   * Always check {@link areFlagsReady} first, or use the asynchronous {@link isEnabled} method instead.
+   *
+   * <p>When a flag is evaluated for the first time, Mixpanel automatically tracks a
+   * "$experiment_started" event with relevant experiment metadata.
+   *
+   * @param {string} featureName The unique identifier for the feature flag
+   * @param {boolean} [fallbackValue=false] The fallback value to return if the flag is not available.
+   *     Defaults to false if not provided.
+   * @returns {boolean} true if the feature is enabled, false otherwise
+   *
+   * @example
+   * // Simple feature toggle
+   * if (mixpanel.flags.areFlagsReady()) {
+   *   if (mixpanel.flags.isEnabledSync('new-checkout', false)) {
+   *     showNewCheckout();
+   *   } else {
+   *     showLegacyCheckout();
+   *   }
+   * }
+   *
+   * @example
+   * // With explicit fallback
+   * const enableBetaFeatures = mixpanel.flags.isEnabledSync('beta-features', true);
+   *
+   * @see isEnabled for asynchronous access
+   * @see getVariantValueSync for non-boolean flag values
    */
   isEnabledSync(featureName, fallbackValue = false) {
     if (!this.areFlagsReady()) {
@@ -109,11 +315,47 @@ export class Flags {
 
   /**
    * Get a feature flag variant asynchronously.
-   * Supports both callback and Promise patterns.
-   * @param {string} featureName - Name of the feature flag
-   * @param {object} fallback - Fallback variant if flag is not available
-   * @param {function} callback - Optional callback function
-   * @returns {Promise|void} Promise if no callback provided, void otherwise
+   *
+   * <p>Returns the complete variant object for a feature flag, including both the variant key
+   * and the variant value. This method works regardless of whether flags are ready, making it
+   * safe to use at any time.
+   *
+   * <p>Supports both Promise and callback patterns for maximum flexibility.
+   *
+   * <p>When a flag is evaluated for the first time, Mixpanel automatically tracks a
+   * "$experiment_started" event with relevant experiment metadata.
+   *
+   * @param {string} featureName The unique identifier for the feature flag
+   * @param {object} fallback The fallback variant object to return if the flag is not available.
+   *     Must include both 'key' and 'value' properties.
+   * @param {function} [callback] Optional callback function that receives the variant object.
+   *     If provided, the method returns void. If omitted, the method returns a Promise.
+   * @returns {Promise<object>|void} Promise that resolves to the variant object if no callback provided,
+   *     void if callback is provided. The variant object has the following structure:
+   *     - key: {string} The variant key (e.g., "control", "treatment")
+   *     - value: {any} The variant value (can be any JSON-serializable type)
+   *     - experiment_id: {string|number} (optional) The experiment ID if this is an experiment
+   *     - is_experiment_active: {boolean} (optional) Whether the experiment is currently active
+   *
+   * @example
+   * // Promise pattern (recommended)
+   * const variant = await mixpanel.flags.getVariant('checkout-flow', {
+   *   key: 'control',
+   *   value: 'standard'
+   * });
+   * console.log(`Using ${variant.key}: ${variant.value}`);
+   *
+   * @example
+   * // Callback pattern
+   * mixpanel.flags.getVariant('pricing-test', {
+   *   key: 'default',
+   *   value: { price: 9.99 }
+   * }, (variant) => {
+   *   console.log(`Price: ${variant.value.price}`);
+   * });
+   *
+   * @see getVariantSync for synchronous access when flags are ready
+   * @see getVariantValue to get only the value without the variant key
    */
   getVariant(featureName, fallback, callback) {
     // If callback provided, use callback pattern
@@ -150,11 +392,45 @@ export class Flags {
 
   /**
    * Get a feature flag variant value asynchronously.
-   * Supports both callback and Promise patterns.
-   * @param {string} featureName - Name of the feature flag
-   * @param {any} fallbackValue - Fallback value if flag is not available
-   * @param {function} callback - Optional callback function
-   * @returns {Promise|void} Promise if no callback provided, void otherwise
+   *
+   * <p>Returns only the value portion of a feature flag variant. This method works regardless
+   * of whether flags are ready, making it safe to use at any time.
+   *
+   * <p>Supports both Promise and callback patterns for maximum flexibility.
+   *
+   * <p>When a flag is evaluated for the first time, Mixpanel automatically tracks a
+   * "$experiment_started" event with relevant experiment metadata.
+   *
+   * @param {string} featureName The unique identifier for the feature flag
+   * @param {any} fallbackValue The fallback value to return if the flag is not available.
+   *     Can be any JSON-serializable type (string, number, boolean, object, array, etc.)
+   * @param {function} [callback] Optional callback function that receives the flag value.
+   *     If provided, the method returns void. If omitted, the method returns a Promise.
+   * @returns {Promise<any>|void} Promise that resolves to the flag value if no callback provided,
+   *     void if callback is provided. The return type matches the type of value configured in
+   *     your Mixpanel project.
+   *
+   * @example
+   * // Promise pattern (recommended)
+   * const buttonColor = await mixpanel.flags.getVariantValue('button-color', 'blue');
+   * applyButtonColor(buttonColor);
+   *
+   * @example
+   * // Promise pattern with object value
+   * const pricing = await mixpanel.flags.getVariantValue('pricing-config', {
+   *   price: 9.99,
+   *   currency: 'USD'
+   * });
+   * displayPrice(pricing.price, pricing.currency);
+   *
+   * @example
+   * // Callback pattern
+   * mixpanel.flags.getVariantValue('theme', 'light', (theme) => {
+   *   applyTheme(theme);
+   * });
+   *
+   * @see getVariantValueSync for synchronous access when flags are ready
+   * @see getVariant to get the full variant object including key and metadata
    */
   getVariantValue(featureName, fallbackValue, callback) {
     // If callback provided, use callback pattern
@@ -191,11 +467,47 @@ export class Flags {
 
   /**
    * Check if a feature flag is enabled asynchronously.
-   * Supports both callback and Promise patterns.
-   * @param {string} featureName - Name of the feature flag
-   * @param {boolean} [fallbackValue=false] - Fallback value if flag is not available
-   * @param {function} [callback] - Optional callback function
-   * @returns {Promise<boolean>|void} Promise if no callback provided, void otherwise
+   *
+   * <p>This is a convenience method for boolean feature flags. It checks if a feature is enabled
+   * by evaluating the variant value as a boolean. This method works regardless of whether flags
+   * are ready, making it safe to use at any time.
+   *
+   * <p>Supports both Promise and callback patterns for maximum flexibility.
+   *
+   * <p>When a flag is evaluated for the first time, Mixpanel automatically tracks a
+   * "$experiment_started" event with relevant experiment metadata.
+   *
+   * @param {string} featureName The unique identifier for the feature flag
+   * @param {boolean} [fallbackValue=false] The fallback value to return if the flag is not available.
+   *     Defaults to false if not provided.
+   * @param {function} [callback] Optional callback function that receives the boolean result.
+   *     If provided, the method returns void. If omitted, the method returns a Promise.
+   * @returns {Promise<boolean>|void} Promise that resolves to true if enabled, false otherwise
+   *     (when no callback provided). Returns void if callback is provided.
+   *
+   * @example
+   * // Promise pattern (recommended)
+   * const isEnabled = await mixpanel.flags.isEnabled('new-checkout', false);
+   * if (isEnabled) {
+   *   showNewCheckout();
+   * } else {
+   *   showLegacyCheckout();
+   * }
+   *
+   * @example
+   * // Callback pattern
+   * mixpanel.flags.isEnabled('beta-features', false, (isEnabled) => {
+   *   if (isEnabled) {
+   *     enableBetaFeatures();
+   *   }
+   * });
+   *
+   * @example
+   * // Default fallback (false)
+   * const showPromo = await mixpanel.flags.isEnabled('show-promo');
+   *
+   * @see isEnabledSync for synchronous access when flags are ready
+   * @see getVariantValue for non-boolean flag values
    */
   isEnabled(featureName, fallbackValue = false, callback) {
     // If callback provided, use callback pattern
@@ -231,16 +543,50 @@ export class Flags {
   }
 
   /**
-   * Update the context used for feature flag evaluation
-   * Aligned with mixpanel-js API
+   * Update the context used for feature flag evaluation.
+   *
+   * <p>Context properties are used to determine which feature flag variants a user should receive
+   * based on targeting rules configured in your Mixpanel project. This allows for personalized
+   * feature experiences based on user attributes, device properties, or custom criteria.
+   *
+   * <p><b>IMPORTANT LIMITATION:</b> This method is <b>only available in JavaScript mode</b>
+   * (Expo/React Native Web). In native mode (iOS/Android), context must be set during initialization
+   * via {@link Mixpanel#init} and cannot be updated at runtime.
+   *
+   * <p>By default, the new context properties are merged with existing context. Set
+   * <code>options.replace = true</code> to completely replace the context instead.
    *
-   * NOTE: This method is only available in JavaScript mode (Expo/React Native Web).
-   * In native mode, context must be set during initialization via FeatureFlagsOptions.
+   * @param {object} newContext New context properties to add or update. Can include any
+   *     JSON-serializable properties that are used in your feature flag targeting rules.
+   *     Common examples include user tier, region, platform version, etc.
+   * @param {object} [options={replace: false}] Configuration options for the update
+   * @param {boolean} [options.replace=false] If true, replaces the entire context instead of merging.
+   *     If false (default), merges new properties with existing context.
+   * @returns {Promise<void>} A promise that resolves when the context has been updated and
+   *     flags have been re-evaluated with the new context
+   * @throws {Error} if called in native mode (iOS/Android)
    *
-   * @param {object} newContext - New context properties to add/update
-   * @param {object} options - Options object
-   * @param {boolean} options.replace - If true, replace entire context instead of merging
-   * @returns {Promise<void>}
+   * @example
+   * // Merge new properties into existing context (JavaScript mode only)
+   * await mixpanel.flags.updateContext({
+   *   user_tier: 'premium',
+   *   region: 'us-west'
+   * });
+   *
+   * @example
+   * // Replace entire context (JavaScript mode only)
+   * await mixpanel.flags.updateContext({
+   *   device_type: 'tablet',
+   *   os_version: '14.0'
+   * }, { replace: true });
+   *
+   * @example
+   * // This will throw an error in native mode
+   * try {
+   *   await mixpanel.flags.updateContext({ tier: 'premium' });
+   * } catch (error) {
+   *   console.error('Context updates not supported in native mode');
+   * }
    */
   async updateContext(newContext, options = { replace: false }) {
     if (this.isNativeMode) {
@@ -256,34 +602,68 @@ export class Flags {
   }
 
   // snake_case aliases for API consistency with mixpanel-js
+
+  /**
+   * Alias for {@link areFlagsReady}. Provided for API consistency with mixpanel-js.
+   * @see areFlagsReady
+   */
   are_flags_ready() {
     return this.areFlagsReady();
   }
 
+  /**
+   * Alias for {@link getVariant}. Provided for API consistency with mixpanel-js.
+   * @see getVariant
+   */
   get_variant(featureName, fallback, callback) {
     return this.getVariant(featureName, fallback, callback);
   }
 
+  /**
+   * Alias for {@link getVariantSync}. Provided for API consistency with mixpanel-js.
+   * @see getVariantSync
+   */
   get_variant_sync(featureName, fallback) {
     return this.getVariantSync(featureName, fallback);
   }
 
+  /**
+   * Alias for {@link getVariantValue}. Provided for API consistency with mixpanel-js.
+   * @see getVariantValue
+   */
   get_variant_value(featureName, fallbackValue, callback) {
     return this.getVariantValue(featureName, fallbackValue, callback);
   }
 
+  /**
+   * Alias for {@link getVariantValueSync}. Provided for API consistency with mixpanel-js.
+   * @see getVariantValueSync
+   */
   get_variant_value_sync(featureName, fallbackValue) {
     return this.getVariantValueSync(featureName, fallbackValue);
   }
 
+  /**
+   * Alias for {@link isEnabled}. Provided for API consistency with mixpanel-js.
+   * @see isEnabled
+   */
   is_enabled(featureName, fallbackValue, callback) {
     return this.isEnabled(featureName, fallbackValue, callback);
   }
 
+  /**
+   * Alias for {@link isEnabledSync}. Provided for API consistency with mixpanel-js.
+   * @see isEnabledSync
+   */
   is_enabled_sync(featureName, fallbackValue) {
     return this.isEnabledSync(featureName, fallbackValue);
   }
 
+  /**
+   * Alias for {@link updateContext}. Provided for API consistency with mixpanel-js.
+   * JavaScript mode only.
+   * @see updateContext
+   */
   update_context(newContext, options) {
     return this.updateContext(newContext, options);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixpanel-react-native",
-  "version": "3.2.0-beta.1",
+  "version": "3.2.0-beta.2",
   "description": "Official React Native Tracking Library for Mixpanel Analytics",
   "main": "index.js",
   "scripts": {
@@ -38,6 +38,7 @@
     "eslint": "^7.11.0",
     "jest": "^26.6.3",
     "jest-fetch-mock": "^3.0.3",
+    "jsdoc": "^4.0.5",
     "metro-react-native-babel-preset": "^0.63.0",
     "react-native": "^0.63.3",
     "react-test-renderer": "16.13.1"