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: Delayed for future release (code present but requires additional testing)

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 and production-ready
• Complete TypeScript definitions
• Comprehensive error handling and fallback support

⏳ Delayed for Future Release

• JavaScript fallback mode (Expo/React Native Web): While the JavaScript implementation code is present in this PR, we've decided to delay support for non-native mode until a later release. Additional testing and validation is needed to ensure the JavaScript implementation meets our quality standards.

Impact: Users running Expo or React Native Web will not have access to Feature Flags functionality in this release. Feature Flags will only be available when the native modules are present (standard React Native with native linking).

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'
});

Future Work

JavaScript mode support will be prioritized for a future release once additional testing is completed.

[Copilot]

Pull Request Overview

This PR adds comprehensive Feature Flags functionality to the Mixpanel React Native SDK, enabling dynamic feature control and A/B testing with support for both native platforms (iOS/Android) and JavaScript fallback mode (Expo/React Native Web).

Key Changes:

• Implements a complete Feature Flags API with both synchronous and asynchronous methods for retrieving flag variants, values, and enabled states
• Adds dual-mode support with native implementations for iOS/Android and JavaScript fallback for Expo/React Native Web
• Integrates automatic experiment tracking with persistent caching using AsyncStorage

Reviewed Changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
javascript/mixpanel-main.js	Stores feature flags configuration options during initialization
javascript/mixpanel-flags.js	Core wrapper class that delegates to native or JavaScript implementations based on platform availability
javascript/mixpanel-flags-js.js	JavaScript implementation with API fetching, caching, and experiment tracking
index.js	Adds lazy-loaded flags property and integrates initialization with feature flags options
ios/MixpanelReactNative.swift	Native iOS implementation of Feature Flags methods with variant conversion helpers
ios/MixpanelReactNative.m	Exposes iOS Feature Flags methods to React Native bridge
android/src/main/java/com/mixpanel/reactnative/MixpanelReactNativeModule.java	Native Android implementation with type conversion handling for React Native bridge limitations

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Pull Request Overview

Copilot reviewed 13 out of 15 changed files in this pull request and generated 5 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Pull Request Overview

Copilot reviewed 13 out of 15 changed files in this pull request and generated 2 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Pull Request Overview

Copilot reviewed 22 out of 25 changed files in this pull request and generated 8 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[msiebert]