mixpanel-react-native 3.1.2 → 3.2.0-beta.0

package/Samples/MixpanelStarter/README.md

@@ -0,0 +1,406 @@
+# MixpanelStarter
+
+A modern, production-ready React Native sample application demonstrating [Mixpanel React Native SDK](https://github.com/mixpanel/mixpanel-react-native) integration with TypeScript, Context API, and best practices.
+
+## 🎯 Purpose
+
+This sample app bridges the gap between basic "Hello World" examples and complex production implementations. It demonstrates **80% of common Mixpanel use cases** with clean, maintainable patterns you can copy directly into your app.
+
+### What Makes This Different
+
+- **Modern Architecture**: Context API + TypeScript strict mode
+- **Production Patterns**: Error handling, loading states, proper lifecycle management
+- **Educational**: Each screen explains what's happening and why
+- **Copy-Paste Ready**: Well-commented code you can use immediately
+
+## ✨ Features Demonstrated
+
+This app showcases 9 core Mixpanel SDK capabilities:
+
+| Feature | Description | Screen |
+|---------|-------------|--------|
+| 🆔 **User Identification** | `identify()`, `alias()`, anonymous-to-identified flow | Onboarding |
+| 👤 **User Profiles** | `getPeople().set()`, `setOnce()` for profile properties | Onboarding |
+| 📊 **Event Tracking** | `track()` with custom properties and metadata | Home |
+| ⏱️ **Timed Events** | `timeEvent()` for automatic duration tracking | Home |
+| 🌐 **Super Properties** | `registerSuperProperties()` for global context | Home |
+| 🚩 **Feature Flags** | `flags.loadFlags()`, `isEnabled()`, dynamic feature control - **FULL INTEGRATION TEST SUITE** | Feature Flags |
+| 🔒 **Privacy Controls** | `optIn/OutTracking()` for GDPR compliance | Settings |
+| 🗑️ **Data Management** | `reset()` for logout/data deletion | Settings |
+| 🚀 **Manual Flush** | `flush()` to force send queued events | Settings |
+
+## 📱 App Structure
+
+The app has 4 tabs:
+
+1. **Onboarding (User ID Tab)**: Demonstrates user identification lifecycle
+2. **Home (Events Tab)**: Shows event tracking and super properties
+3. **Feature Flags**: **Comprehensive integration test suite** - exercises all 8 public API methods, Promise/Callback patterns, edge cases, and type coercion
+4. **Settings**: Privacy controls and data management
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Node.js >= 20
+- React Native development environment set up ([guide](https://reactnative.dev/docs/environment-setup))
+- Mixpanel project token ([get one here](https://mixpanel.com/register))
+
+### Installation
+
+```bash
+# 1. Navigate to this directory
+cd Samples/MixpanelStarter
+
+# 2. Install dependencies
+npm install
+
+# 3. Install iOS dependencies (macOS only)
+cd ios && pod install && cd ..
+
+# 4. Configure your Mixpanel token
+cp .env.example .env
+# Edit .env and add your token: MIXPANEL_TOKEN=your_token_here
+```
+
+### Running the App
+
+```bash
+# iOS
+npm run ios
+
+# Android
+npm run android
+```
+
+**Note**: If you don't set a token in `.env`, the app will use a placeholder token. You'll see events in the console but they won't reach Mixpanel.
+
+## 🏗️ Project Structure
+
+```
+MixpanelStarter/
+├── src/
+│   ├── contexts/
+│   │   └── MixpanelContext.tsx      # Context Provider + useMixpanel hook
+│   ├── screens/
+│   │   ├── OnboardingScreen.tsx     # User identification demos
+│   │   ├── HomeScreen.tsx           # Event tracking patterns
+│   │   ├── FeatureFlagsScreen.tsx   # Feature flags integration tests
+│   │   └── SettingsScreen.tsx       # Privacy & data management
+│   ├── components/
+│   │   ├── ActionButton.tsx         # Reusable button component
+│   │   ├── InfoCard.tsx             # Info display card
+│   │   ├── FlagCard.tsx             # Flag display component
+│   │   ├── TestResultDisplay.tsx    # Test results visualization
+│   │   ├── EventTrackingLog.tsx     # Event history component
+│   │   └── ErrorBoundary.tsx        # Error handling wrapper
+│   ├── types/
+│   │   ├── mixpanel.types.ts        # TypeScript definitions
+│   │   └── flags.types.ts           # Feature flags test types
+│   ├── constants/
+│   │   └── tracking.ts              # Event names & properties
+│   └── App.tsx                       # Navigation setup
+├── __tests__/
+│   └── MixpanelContext.test.tsx     # Basic context tests
+└── .env.example                      # Environment template
+```
+
+## 📖 Key Patterns (Copy These!)
+
+### 1. Context Setup
+
+```typescript
+// Wrap your app root with MixpanelProvider
+<MixpanelProvider token="YOUR_TOKEN" trackAutomaticEvents={true}>
+  <App />
+</MixpanelProvider>
+
+// Use in any component
+const { mixpanel, isInitialized, track, identify } = useMixpanel();
+```
+
+**Why?** Provides app-wide access without prop drilling. Handles initialization and loading states automatically.
+
+### 2. Event Tracking with Constants
+
+```typescript
+// Define event names as constants
+const Events = {
+  PRODUCT_VIEWED: 'Product Viewed',
+  VIDEO_COMPLETED: 'Video Completed',
+};
+
+// Track events
+track(Events.PRODUCT_VIEWED, {
+  product_id: 'prod-123',
+  product_name: 'Sample Product',
+  timestamp: new Date().toISOString(),
+});
+```
+
+**Why?** Constants prevent typos, enable autocomplete, and make refactoring easier.
+
+### 3. User Identification Flow
+
+```typescript
+// Get the current anonymous ID
+const previousId = await mixpanel.getDistinctId();
+
+// Identify the user
+identify(userId);
+
+// Link previous anonymous events
+alias(userId, previousId);
+
+// Set profile properties
+mixpanel.getPeople().set({
+  $email: userId,
+  signup_date: new Date().toISOString(),
+});
+```
+
+**Why?** Preserves event history when users transition from anonymous to identified.
+
+### 4. Super Properties for Global Context
+
+```typescript
+// Set once for all events
+mixpanel.registerSuperProperties({
+  'App Version': '1.0.0',
+  'Dark Mode': darkModeEnabled,
+  'Platform': Platform.OS,
+});
+
+// These are automatically included in every event
+```
+
+**Why?** Eliminates repetitive property passing. Perfect for user preferences and app state.
+
+### 5. Feature Flags for Dynamic Control
+
+```typescript
+// Enable feature flags during initialization
+await mixpanel.init(false, {}, undefined, false, {
+  enabled: true,
+});
+
+// Load flags from Mixpanel
+await mixpanel.flags.loadFlags();
+
+// Check if flags are ready
+const ready = mixpanel.flags.areFlagsReady();
+
+// Synchronous flag evaluation (fast, uses cached values)
+const isEnabled = mixpanel.flags.isEnabledSync('feature-key', false);
+const value = mixpanel.flags.getVariantValueSync('feature-key', 'default');
+
+// Asynchronous flag evaluation (ensures latest values)
+const enabled = await mixpanel.flags.isEnabled('feature-key', false);
+const variant = await mixpanel.flags.getVariant('feature-key', {
+  key: 'feature-key',
+  value: null,
+});
+
+```
+
+**Why?** Enables remote feature control, A/B testing, and gradual rollouts without app updates. Perfect for experimentation and user segmentation.
+
+#### Feature Flags Testing Screen
+
+The Feature Flags screen is a **full integration test suite** with:
+
+- **4 Test Modes**: Sync, Async (Promise), Edge Cases, Type Coercion
+- **12 Pre-configured Flags**: Boolean gates, string experiments, dynamic configs
+- **Real-time Results**: Execution time, type detection, fallback tracking
+- **Event Monitoring**: Live `$experiment_started` event tracking
+- **All API Methods**: getVariantSync, getVariantValueSync, isEnabledSync, getVariant, getVariantValue, isEnabled (both Promise and Callback patterns)
+
+Use this screen during development to verify Feature Flags functionality!
+
+### 6. GDPR-Compliant Logout
+
+```typescript
+// Before logout
+track('User Logged Out');
+await flush();              // Send pending events
+reset();                    // Clear all data
+```
+
+**Why?** Ensures data is sent before clearing, and respects user privacy.
+
+## 🎓 Learning Resources
+
+### In-App Learning
+
+Each screen includes a "What's Happening?" card that explains:
+- Which SDK methods are being used
+- Why you'd use this pattern
+- What data is being sent to Mixpanel
+
+### Code Comments
+
+Every key function includes comments explaining:
+- **What** it does
+- **Why** you'd use this pattern
+- **When** to apply it in your app
+
+## 🧪 Testing
+
+```bash
+# Run tests
+npm test
+
+# Run with coverage
+npm test -- --coverage
+```
+
+## 🔧 Configuration
+
+### Environment Variables
+
+Create a `.env` file (see `.env.example`):
+
+```bash
+MIXPANEL_TOKEN=your_project_token_here
+```
+
+### Mixpanel Options
+
+In `src/App.tsx`, you can configure:
+
+```typescript
+<MixpanelProvider
+  token={token}
+  trackAutomaticEvents={true}  // Track app lifecycle events
+  useNative={true}             // Use native iOS/Android SDKs
+>
+```
+
+## 📚 Next Steps
+
+### For Learning
+
+1. Open the app and explore each screen
+2. Read the "What's Happening?" cards to understand each pattern
+3. Check Mixpanel dashboard to see events arrive
+4. Modify the code and observe changes
+
+### For Integration
+
+1. Copy the `contexts/MixpanelContext.tsx` pattern into your app
+2. Define your event names in `constants/tracking.ts`
+3. Use `useMixpanel()` hook in your components
+4. See [INTEGRATION_GUIDE.md](./INTEGRATION_GUIDE.md) for step-by-step instructions
+
+## 🤔 Common Questions
+
+### Q: Which events should I track?
+
+**A:** Focus on user actions that indicate value or progress:
+- Key conversions (signup, purchase, subscription)
+- Feature usage (search, filter, share)
+- Content engagement (view, complete, like)
+
+Avoid tracking:
+- Every button click (too noisy)
+- Internal state changes (not user-facing)
+- PII without consent (privacy violation)
+
+### Q: When should I use super properties vs. event properties?
+
+**A:**
+- **Super Properties**: User preferences, app state, device info (changes infrequently, applies to all events)
+- **Event Properties**: Action-specific data (product ID, video title, search query)
+
+### Q: How do I test without sending real events?
+
+**A:**
+1. Use a test project token from Mixpanel
+2. Enable logging: `mixpanel.setLoggingEnabled(true)`
+3. Check console for event details
+4. Use opt-out during development: `mixpanel.optOutTracking()`
+
+### Q: What's the difference between native and JavaScript mode?
+
+**A:**
+- **Native (default)**: Uses iOS Swift SDK and Android Java SDK. Better performance, automatic properties.
+- **JavaScript**: Pure JS implementation. Required for Expo and web. More portable but fewer automatic properties.
+
+Set in `MixpanelProvider`: `useNative={true}` or `useNative={false}`
+
+## 🐛 Troubleshooting
+
+### Events not appearing in Mixpanel?
+
+1. Check token is correct: `getDistinctId()` should return a value
+2. Verify network connectivity
+3. Check opt-out status: `hasOptedOutTracking()`
+4. Manually flush: `flush()` to send immediately
+5. Enable logging: `setLoggingEnabled(true)`
+
+### TypeScript errors?
+
+```bash
+# Clear caches
+npm start -- --reset-cache
+
+# Rebuild
+cd ios && pod install && cd ..
+npm run ios
+```
+
+### Build errors?
+
+```bash
+# Clean iOS build
+cd ios && xcodebuild clean && cd ..
+
+# Clean Android build
+cd android && ./gradlew clean && cd ..
+```
+
+## 📝 Design Decisions
+
+### Why Context API over Redux/MobX?
+
+- **Simplicity**: No boilerplate, minimal concepts
+- **Standards**: Built into React, widely understood
+- **Sufficient**: Mixpanel state is simple (one instance, few methods)
+
+### Why TypeScript strict mode?
+
+- **Safety**: Catches errors at compile time
+- **Documentation**: Types serve as inline docs
+- **Refactoring**: IDE support for safe code changes
+
+### Why Bottom Tabs over Stack Navigation?
+
+- **Clarity**: Each tab demonstrates a distinct concept
+- **Simplicity**: Fewer navigation concepts to learn
+- **Focus**: User isn't distracted by complex flows
+
+## 🤝 Contributing
+
+Found an issue or want to improve this sample?
+
+1. This is a reference implementation, so changes should be broadly applicable
+2. Keep patterns simple and well-commented
+3. Ensure TypeScript strict mode passes
+4. Test on both iOS and Android
+
+## 📄 License
+
+This sample app follows the same license as the [Mixpanel React Native SDK](https://github.com/mixpanel/mixpanel-react-native).
+
+## 🔗 Resources
+
+- [Mixpanel React Native SDK Docs](https://docs.mixpanel.com/docs/tracking/advanced/react-native)
+- [Mixpanel Best Practices](https://docs.mixpanel.com/docs/tracking/how-tos/events-and-properties)
+- [React Native Docs](https://reactnative.dev/)
+- [React Navigation Docs](https://reactnavigation.org/)
+
+---
+
+**Made with ❤️ to help you integrate Mixpanel quickly and correctly.**
+
+Questions? Check out the [Integration Guide](./INTEGRATION_GUIDE.md) or [Mixpanel Community](https://community.mixpanel.com/).

package/Samples/MixpanelStarter/__tests__/MixpanelContext.test.tsx

@@ -0,0 +1,63 @@
+import React from 'react';
+import {render, waitFor} from '@testing-library/react-native';
+import {Text} from 'react-native';
+import {MixpanelProvider, useMixpanel} from '../src/contexts/MixpanelContext';
+
+// Mock the Mixpanel SDK
+jest.mock('mixpanel-react-native', () => ({
+  Mixpanel: jest.fn().mockImplementation(() => ({
+    init: jest.fn().mockResolvedValue(undefined),
+    registerSuperProperties: jest.fn(),
+    setLoggingEnabled: jest.fn(),
+    track: jest.fn(),
+    identify: jest.fn(),
+    alias: jest.fn(),
+    reset: jest.fn(),
+    flush: jest.fn().mockResolvedValue(undefined),
+  })),
+}));
+
+// Test component that uses the hook
+const TestComponent = () => {
+  const {isInitialized, isLoading, error} = useMixpanel();
+
+  return (
+    <>
+      <Text testID="initialized">{isInitialized ? 'true' : 'false'}</Text>
+      <Text testID="loading">{isLoading ? 'true' : 'false'}</Text>
+      <Text testID="error">{error ? error.message : 'none'}</Text>
+    </>
+  );
+};
+
+describe('MixpanelContext', () => {
+  it('should provide Mixpanel context to children', async () => {
+    const {getByTestId} = render(
+      <MixpanelProvider token="test-token">
+        <TestComponent />
+      </MixpanelProvider>,
+    );
+
+    // Initially loading
+    expect(getByTestId('loading').props.children).toBe('true');
+    expect(getByTestId('initialized').props.children).toBe('false');
+
+    // Wait for initialization
+    await waitFor(() => {
+      expect(getByTestId('initialized').props.children).toBe('true');
+      expect(getByTestId('loading').props.children).toBe('false');
+      expect(getByTestId('error').props.children).toBe('none');
+    });
+  });
+
+  it('should throw error when used outside provider', () => {
+    // Suppress console.error for this test
+    const consoleError = jest.spyOn(console, 'error').mockImplementation();
+
+    expect(() => {
+      render(<TestComponent />);
+    }).toThrow('useMixpanel must be used within a MixpanelProvider');
+
+    consoleError.mockRestore();
+  });
+});

package/Samples/MixpanelStarter/android/app/build.gradle

@@ -0,0 +1,119 @@
+apply plugin: "com.android.application"
+apply plugin: "org.jetbrains.kotlin.android"
+apply plugin: "com.facebook.react"
+
+/**
+ * This is the configuration block to customize your React Native Android app.
+ * By default you don't need to apply any configuration, just uncomment the lines you need.
+ */
+react {
+    /* Folders */
+    //   The root of your project, i.e. where "package.json" lives. Default is '../..'
+    // root = file("../../")
+    //   The folder where the react-native NPM package is. Default is ../../node_modules/react-native
+    // reactNativeDir = file("../../node_modules/react-native")
+    //   The folder where the react-native Codegen package is. Default is ../../node_modules/@react-native/codegen
+    // codegenDir = file("../../node_modules/@react-native/codegen")
+    //   The cli.js file which is the React Native CLI entrypoint. Default is ../../node_modules/react-native/cli.js
+    // cliFile = file("../../node_modules/react-native/cli.js")
+
+    /* Variants */
+    //   The list of variants to that are debuggable. For those we're going to
+    //   skip the bundling of the JS bundle and the assets. By default is just 'debug'.
+    //   If you add flavors like lite, prod, etc. you'll have to list your debuggableVariants.
+    // debuggableVariants = ["liteDebug", "prodDebug"]
+
+    /* Bundling */
+    //   A list containing the node command and its flags. Default is just 'node'.
+    // nodeExecutableAndArgs = ["node"]
+    //
+    //   The command to run when bundling. By default is 'bundle'
+    // bundleCommand = "ram-bundle"
+    //
+    //   The path to the CLI configuration file. Default is empty.
+    // bundleConfig = file(../rn-cli.config.js)
+    //
+    //   The name of the generated asset file containing your JS bundle
+    // bundleAssetName = "MyApplication.android.bundle"
+    //
+    //   The entry file for bundle generation. Default is 'index.android.js' or 'index.js'
+    // entryFile = file("../js/MyApplication.android.js")
+    //
+    //   A list of extra flags to pass to the 'bundle' commands.
+    //   See https://github.com/react-native-community/cli/blob/main/docs/commands.md#bundle
+    // extraPackagerArgs = []
+
+    /* Hermes Commands */
+    //   The hermes compiler command to run. By default it is 'hermesc'
+    // hermesCommand = "$rootDir/my-custom-hermesc/bin/hermesc"
+    //
+    //   The list of flags to pass to the Hermes compiler. By default is "-O", "-output-source-map"
+    // hermesFlags = ["-O", "-output-source-map"]
+
+    /* Autolinking */
+    autolinkLibrariesWithApp()
+}
+
+/**
+ * Set this to true to Run Proguard on Release builds to minify the Java bytecode.
+ */
+def enableProguardInReleaseBuilds = false
+
+/**
+ * The preferred build flavor of JavaScriptCore (JSC)
+ *
+ * For example, to use the international variant, you can use:
+ * `def jscFlavor = io.github.react-native-community:jsc-android-intl:2026004.+`
+ *
+ * The international variant includes ICU i18n library and necessary data
+ * allowing to use e.g. `Date.toLocaleString` and `String.localeCompare` that
+ * give correct results when using with locales other than en-US. Note that
+ * this variant is about 6MiB larger per architecture than default.
+ */
+def jscFlavor = 'io.github.react-native-community:jsc-android:2026004.+'
+
+android {
+    ndkVersion rootProject.ext.ndkVersion
+    buildToolsVersion rootProject.ext.buildToolsVersion
+    compileSdk rootProject.ext.compileSdkVersion
+
+    namespace "com.mixpanelstarter"
+    defaultConfig {
+        applicationId "com.mixpanelstarter"
+        minSdkVersion rootProject.ext.minSdkVersion
+        targetSdkVersion rootProject.ext.targetSdkVersion
+        versionCode 1
+        versionName "1.0"
+    }
+    signingConfigs {
+        debug {
+            storeFile file('debug.keystore')
+            storePassword 'android'
+            keyAlias 'androiddebugkey'
+            keyPassword 'android'
+        }
+    }
+    buildTypes {
+        debug {
+            signingConfig signingConfigs.debug
+        }
+        release {
+            // Caution! In production, you need to generate your own keystore file.
+            // see https://reactnative.dev/docs/signed-apk-android.
+            signingConfig signingConfigs.debug
+            minifyEnabled enableProguardInReleaseBuilds
+            proguardFiles getDefaultProguardFile("proguard-android.txt"), "proguard-rules.pro"
+        }
+    }
+}
+
+dependencies {
+    // The version of react-native is set by the React Native Gradle Plugin
+    implementation("com.facebook.react:react-android")
+
+    if (hermesEnabled.toBoolean()) {
+        implementation("com.facebook.react:hermes-android")
+    } else {
+        implementation jscFlavor
+    }
+}

package/Samples/MixpanelStarter/android/app/proguard-rules.pro

@@ -0,0 +1,10 @@
+# Add project specific ProGuard rules here.
+# By default, the flags in this file are appended to flags specified
+# in /usr/local/Cellar/android-sdk/24.3.3/tools/proguard/proguard-android.txt
+# You can edit the include path and order by changing the proguardFiles
+# directive in build.gradle.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# Add any project specific keep options here:

package/Samples/MixpanelStarter/android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,27 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <application
+      android:name=".MainApplication"
+      android:label="@string/app_name"
+      android:icon="@mipmap/ic_launcher"
+      android:roundIcon="@mipmap/ic_launcher_round"
+      android:allowBackup="false"
+      android:theme="@style/AppTheme"
+      android:usesCleartextTraffic="${usesCleartextTraffic}"
+      android:supportsRtl="true">
+      <activity
+        android:name=".MainActivity"
+        android:label="@string/app_name"
+        android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode"
+        android:launchMode="singleTask"
+        android:windowSoftInputMode="adjustResize"
+        android:exported="true">
+        <intent-filter>
+            <action android:name="android.intent.action.MAIN" />
+            <category android:name="android.intent.category.LAUNCHER" />
+        </intent-filter>
+      </activity>
+    </application>
+</manifest>

package/Samples/MixpanelStarter/android/app/src/main/java/com/mixpanelstarter/MainActivity.kt

@@ -0,0 +1,22 @@
+package com.mixpanelstarter
+
+import com.facebook.react.ReactActivity
+import com.facebook.react.ReactActivityDelegate
+import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.fabricEnabled
+import com.facebook.react.defaults.DefaultReactActivityDelegate
+
+class MainActivity : ReactActivity() {
+
+  /**
+   * Returns the name of the main component registered from JavaScript. This is used to schedule
+   * rendering of the component.
+   */
+  override fun getMainComponentName(): String = "MixpanelStarter"
+
+  /**
+   * Returns the instance of the [ReactActivityDelegate]. We use [DefaultReactActivityDelegate]
+   * which allows you to enable New Architecture with a single boolean flags [fabricEnabled]
+   */
+  override fun createReactActivityDelegate(): ReactActivityDelegate =
+      DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled)
+}

package/Samples/MixpanelStarter/android/app/src/main/java/com/mixpanelstarter/MainApplication.kt

@@ -0,0 +1,27 @@
+package com.mixpanelstarter
+
+import android.app.Application
+import com.facebook.react.PackageList
+import com.facebook.react.ReactApplication
+import com.facebook.react.ReactHost
+import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative
+import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
+
+class MainApplication : Application(), ReactApplication {
+
+  override val reactHost: ReactHost by lazy {
+    getDefaultReactHost(
+      context = applicationContext,
+      packageList =
+        PackageList(this).packages.apply {
+          // Packages that cannot be autolinked yet can be added manually here, for example:
+          // add(MyReactNativePackage())
+        },
+    )
+  }
+
+  override fun onCreate() {
+    super.onCreate()
+    loadReactNative(this)
+  }
+}