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
• Dual Mode Support: Works in both native mode (iOS/Android) and JavaScript fallback mode (Expo/React Native Web)
• 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
• updateContext() - Update targeting context at runtime

Platform Support

• iOS: Native implementation using Mixpanel Swift SDK
• Android: Native implementation using Mixpanel Android SDK
• JavaScript: Full fallback implementation for Expo and React Native Web
• TypeScript: Complete type definitions for all Feature Flags APIs

Features

• Automatic experiment tracking with $experiment_started events
• Persistent caching using AsyncStorage in JavaScript mode
• Graceful error handling with fallback values
• Context-aware targeting with runtime updates
• Lazy loading to minimize performance impact

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)

Usage Example

// Initialize with Feature Flags
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'
});

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

[nitpick] The optional chaining with double null-coalescing creates complex logic. If config or getServerURL doesn't exist, this falls back to the default URL, but this should be explicitly validated since serverURL is critical for API calls. Consider extracting this to a helper method with clear error handling.

[Copilot]

[nitpick] The jq command uses complex pipe operations that are hard to read and debug. The comment states 'jq is pre-installed on macOS GitHub Actions runners', but this assumption could break if the runner environment changes. Consider adding a check for jq availability before using it.

Suggested change

	# Note: jq is pre-installed on macOS GitHub Actions runners
	SIMULATOR_ID=$(xcrun simctl list devices available -j | jq -r '.devices | to_entries[] | .value[] | select(.name | contains("iPhone")) | .udid' | head -n 1)
	if [ -z "$SIMULATOR_ID" ]; then
	echo "Error: No iPhone simulator found"
	# Note: jq is pre-installed on macOS GitHub Actions runners, but check to be sure
	command -v jq >/dev/null 2>&1 || { echo >&2 "jq is required but not installed. Aborting."; exit 1; }
	SIMULATOR_ID=$(xcrun simctl list devices available -j | jq -r '.devices | to_entries[] | .value[] | select(.name | contains("iPhone")) | .udid' | head -n 1)
	if [ -z "$SIMULATOR_ID" ]; then

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

The loadCachedFlags() method is called in the constructor but is async. This call will not be awaited, which means the flags may not be loaded when the instance is first used. Consider making the constructor initialization explicit or documenting that cached flags load asynchronously.

[Copilot]

[nitpick] While jq is commonly available on macOS GitHub Actions runners, it's better to explicitly verify or install it to avoid potential failures if the runner configuration changes.

Suggested change

	- name: Boot iOS Simulator
	run: |
	# Get list of available iPhone simulators
	# Note: jq is pre-installed on macOS GitHub Actions runners
	- name: Ensure jq is installed
	run: |
	if ! command -v jq >/dev/null 2>&1; then
	echo "jq not found, installing with Homebrew..."
	brew install jq
	else
	echo "jq is already installed"
	fi
	- name: Boot iOS Simulator
	run: |
	# Get list of available iPhone simulators