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  expo-feature-flags-sample #346
•  2  Add Feature Flags support to React Native SDK #331 👈
•  1  Fix getUseIpAddressForGeolocation always returning true #316

[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]

[brunocentanaro]

Hello, is there an ETA for this to be merged?

[jaredmixpanel]

@brunocentanaro No ETA at the moment, it's still in beta: https://github.com/mixpanel/mixpanel-react-native/blob/feature/add-feature-flags-support/FEATURE_FLAGS_QUICKSTART.md

[Copilot]

Pull request overview

Copilot reviewed 37 out of 46 changed files in this pull request and generated no new comments.

Files not reviewed (2)

• Samples/MixpanelExample/ios/MixpanelExample.xcworkspace/contents.xcworkspacedata: Language not supported
• Samples/MixpanelExpo/package-lock.json: Language not supported

Comments suppressed due to low confidence (2)

docs/index.html:1

• The documentation timestamp shows a date in the future (November 7, 2025). This should be corrected to reflect the actual date when the documentation was generated.
  javascript/mixpanel-persistent.js:1
• Good catch adding the missing return statement. This was a bug where the Promise wasn't being returned, potentially causing initialization timing issues.