Add Feature Flags support to React Native SDK

[jaredmixpanel]

Summary

This PR adds comprehensive Feature Flags functionality to the Mixpanel React Native SDK, enabling dynamic feature control and A/B testing capabilities.

Changes

Core Implementation

• Flags API: New mixpanel.flags property providing access to feature flags functionality
• Native Mode: Fully functional in native mode (iOS/Android) using native SDK implementations
• Dual Async Patterns: All async methods support both callback and Promise patterns

API Methods

• loadFlags() - Manually fetch flags from server
• areFlagsReady() - Check if flags are loaded and ready
• getVariantSync() / getVariant() - Get full variant object
• getVariantValueSync() / getVariantValue() - Get variant value only
• isEnabledSync() / isEnabled() - Check if feature is enabled

Platform Support

• iOS: Native implementation using Mixpanel Swift SDK ✅
• Android: Native implementation using Mixpanel Android SDK ✅
• JavaScript Mode: JavaScript implementation included ✅

Features

• Automatic experiment tracking with $experiment_started events
• Graceful error handling with fallback values
• Context-aware targeting with runtime updates
• Lazy loading to minimize performance impact

Implementation Status

✅ Ready for Production

• Native mode (iOS/Android) fully tested
• Non-native mode (JS) fully tested
• Complete TypeScript definitions
• Comprehensive error handling and fallback support

Backward Compatibility

This change is fully backward compatible:

• Lazy-loaded (only initialized when accessed)
• Optional (can be disabled via initialization options)
• Non-breaking (all existing functionality unchanged)
• Gracefully degrades when native modules unavailable

Usage Example

// Initialize with Feature Flags (native mode only)
const mixpanel = new Mixpanel('YOUR_TOKEN');
await mixpanel.init(false, {}, 'https://api.mixpanel.com', true, {
  enabled: true,
  context: { platform: 'mobile' }
});

// Access flags synchronously when ready
if (mixpanel.flags.areFlagsReady()) {
  const isEnabled = mixpanel.flags.isEnabledSync('new-feature', false);
  const color = mixpanel.flags.getVariantValueSync('button-color', 'blue');
}

// Or use async methods
const variant = await mixpanel.flags.getVariant('checkout-flow', {
  key: 'control',
  value: 'standard'
});

---

This is part 2 of 3 in a stack made with GitButler:

•  3  #346
•  2  #331 👈
•  1  #316