mixpanel-react-native 3.1.2 → 3.1.3

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

@@ -0,0 +1,97 @@
+# Feature Flags JavaScript Mode - Test Results & Findings
+
+## Summary
+JavaScript mode for feature flags has been successfully enabled for testing via environment variable. The implementation is mostly working but has some async operation issues that need resolution.
+
+## What's Working ✅
+1. **Environment Variable Control**: `MIXPANEL_ENABLE_JS_FLAGS=true` successfully enables JavaScript mode
+2. **Basic Initialization**: Mixpanel instance creates correctly in JavaScript mode
+3. **Synchronous Methods**: All sync methods work as expected:
+   - `areFlagsReady()`
+   - `getVariantSync()`
+   - `getVariantValueSync()`
+   - `isEnabledSync()`
+4. **Snake-case Aliases**: API compatibility methods working
+5. **Error Handling**: Gracefully handles null feature names
+
+## Issues Found & Fixed ✅
+
+### 1. Async Methods Timeout (FIXED)
+The following async methods were hanging indefinitely (5+ second timeout):
+- `loadFlags()`
+- `getVariant()` (async version)
+- `getVariantValue()` (async version)
+- `isEnabled()` (async version)
+- `updateContext()`
+
+**Root Cause**: The MixpanelNetwork.sendRequest method was:
+1. Always sending POST requests, even for the flags endpoint (which should be GET)
+2. Retrying all failed requests with exponential backoff (up to 5 retries)
+3. For GET requests returning 404, this caused 5+ seconds of retry delays
+
+**Solution**: Modified `javascript/mixpanel-network.js`:
+- Detect GET requests (when data is null/undefined)
+- Send proper GET requests without body for flags endpoint
+- Don't retry GET requests on client errors (4xx status codes)
+- Only retry POST requests or server errors (5xx)
+
+### 2. Test Suite Hanging (RESOLVED)
+- **Initial Issue**: Tests would not exit after completion
+- **Cause**: Recurring intervals from `mixpanel-core.js` queue processing
+- **Solution**: Removed fake timers and added proper cleanup in `afterEach`
+
+## Code Changes Made
+
+### 1. index.js (Lines 89-95)
+```javascript
+// 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."
+  );
+}
+```
+
+### 2. Test File Created
+- Created `__tests__/flags-js-mode.test.js` with comprehensive JavaScript mode tests
+- Tests pass AsyncStorage mock as 4th parameter to Mixpanel constructor
+- Proper cleanup to prevent hanging
+
+## Next Steps
+
+### Immediate (Before Beta Release)
+1. ✅ **Fix Async Methods**: COMPLETE - Fixed network layer to handle GET requests properly
+2. **Test in Real Expo App**: Run in actual Expo environment (not just unit tests)
+3. **Performance Testing**: Verify AsyncStorage performance with large flag sets
+
+### Future Enhancements
+1. **Remove Blocking Check**: Once stable, remove environment variable requirement
+2. **Documentation**: Update FEATURE_FLAGS_QUICKSTART.md with JS mode examples
+3. **Migration Guide**: Document differences between native and JS modes
+
+## Testing Commands
+
+```bash
+# Run JavaScript mode tests
+MIXPANEL_ENABLE_JS_FLAGS=true npm test -- --testPathPattern=flags-js-mode
+
+# Run in Expo app
+cd Samples/MixpanelExpo
+MIXPANEL_ENABLE_JS_FLAGS=true npm start
+```
+
+## Risk Assessment
+- **Low Risk**: Core functionality works, follows established patterns
+- **Low Risk**: All async operations now working correctly
+- **Mitigation**: Keep behind environment variable until Expo testing complete
+
+## Recommendations
+1. ✅ Async methods fixed - ready for beta testing
+2. Test in real Expo environment before removing environment variable guard
+3. Consider adding a `jsMode` flag to initialization options for cleaner API
+4. Monitor network performance with real API endpoints

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

@@ -0,0 +1,348 @@
+# Feature Flags Quick Start Guide (Beta)
+
+> **Beta Version:** `3.2.0-beta.2`
+> **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@beta
+```
+
+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/Samples/MixpanelExpo/.yalc/mixpanel-react-native/MixpanelReactNative.podspec

@@ -19,5 +19,5 @@ Pod::Spec.new do |s|
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES' }
 
   s.dependency "React-Core"
-  s.dependency "Mixpanel-swift", '5.0.0'
+  s.dependency "Mixpanel-swift", '5.1.3'
 end