mixpanel-react-native 3.1.2 → 3.1.3

package/Samples/MixpanelStarter/CLAUDE.md

@@ -0,0 +1,538 @@
+# CLAUDE.md - MixpanelStarter Sample App
+
+This file provides guidance to Claude Code when working with the MixpanelStarter sample application.
+
+## Project Overview
+
+**Purpose**: Modern, production-ready React Native sample app demonstrating Mixpanel SDK integration with TypeScript, Context API, and best practices.
+
+**Target Audience**: Developers learning to integrate Mixpanel into their React Native apps.
+
+**Positioning**: Bridges the gap between SimpleMixpanel (too basic) and MixpanelDemo (too complex), demonstrating 80% of common use cases.
+
+## Quick Reference
+
+### Tech Stack
+- **React Native**: 0.82.1
+- **React**: 19.1.1
+- **TypeScript**: Strict mode enabled
+- **Navigation**: React Navigation 7.x with bottom tabs
+- **State Management**: Context API pattern
+- **Testing**: Jest with React Native Testing Library
+
+### Key Dependencies
+- `mixpanel-react-native` - Main SDK (file:../..)
+- `@react-native-async-storage/async-storage` - Required for Mixpanel
+- `@react-navigation/native` + `@react-navigation/bottom-tabs` - Navigation
+- `react-native-dotenv` - Environment variables
+
+## Commands
+
+### Development
+```bash
+# Install dependencies
+npm install
+cd ios && pod install && cd ..
+
+# Run app
+npm run ios        # iOS simulator
+npm run android    # Android emulator
+npm start          # Start Metro bundler
+
+# Testing
+npm test           # Run Jest tests
+npm test -- --coverage  # With coverage
+npx tsc --noEmit   # TypeScript compilation check
+
+# Linting
+npm run lint       # Run ESLint
+```
+
+### Environment Setup
+```bash
+# Create environment file
+cp .env.example .env
+# Edit .env and set: MIXPANEL_TOKEN=your_token_here
+```
+
+### Troubleshooting Commands
+```bash
+# Clear Metro cache
+npm start -- --reset-cache
+
+# Clean iOS build
+cd ios && xcodebuild clean && cd ..
+
+# Clean Android build
+cd android && ./gradlew clean && cd ..
+
+# Reinstall dependencies
+rm -rf node_modules && npm install
+```
+
+## Architecture & Code Patterns
+
+### Core Architecture Pattern: Context API + Custom Hook
+
+```typescript
+// Provider wraps app root (src/App.tsx)
+<MixpanelProvider token={token} trackAutomaticEvents={true}>
+  <NavigationContainer>
+    {/* app content */}
+  </NavigationContainer>
+</MixpanelProvider>
+
+// Hook usage in any component
+const { mixpanel, isInitialized, track, identify } = useMixpanel();
+```
+
+**Why Context API?**
+- Simple, no boilerplate
+- Built into React (widely understood)
+- Sufficient for Mixpanel's simple state needs
+- Avoids prop drilling
+
+### File Naming Conventions
+- **Components**: PascalCase (ActionButton.tsx, InfoCard.tsx)
+- **Screens**: PascalCase with "Screen" suffix (OnboardingScreen.tsx)
+- **Contexts**: PascalCase with "Context" suffix (MixpanelContext.tsx)
+- **Types**: kebab-case with .types.ts suffix (mixpanel.types.ts)
+- **Constants**: kebab-case (tracking.ts)
+
+### Import Order Pattern
+```typescript
+// 1. External libraries (React, React Native)
+import React, {useState, useEffect} from 'react';
+import {View, Text, StyleSheet} from 'react-native';
+
+// 2. Navigation
+import {NavigationContainer} from '@react-navigation/native';
+
+// 3. Internal contexts/hooks
+import {useMixpanel} from '../contexts/MixpanelContext';
+
+// 4. Components
+import {ActionButton} from '../components/ActionButton';
+
+// 5. Constants/types
+import {Events, Properties} from '../constants/tracking';
+```
+
+### Event Tracking Pattern
+```typescript
+// Always use constants (prevents typos, enables autocomplete)
+import {Events, Properties} from '../constants/tracking';
+
+// Check initialization before tracking
+if (isInitialized) {
+  track(Events.SCREEN_VIEWED, {
+    [Properties.SCREEN_NAME]: 'Home',
+    [Properties.TIMESTAMP]: new Date().toISOString(),
+  });
+}
+
+// Track on mount with useEffect
+useEffect(() => {
+  if (isInitialized) {
+    track(Events.SCREEN_VIEWED, {...});
+  }
+}, [isInitialized, track]);
+```
+
+### User Identification Pattern
+```typescript
+// Complete signup flow (OnboardingScreen.tsx:52-90)
+const previousId = await mixpanel.getDistinctId();
+identify(userId);                    // Set new identity
+await alias(userId, previousId);     // Link anonymous events
+mixpanel.getPeople().set({...});     // Set profile
+mixpanel.getPeople().setOnce({...}); // Set immutable properties
+track(Events.USER_SIGNED_UP, {...}); // Track event
+```
+
+### Privacy-Compliant Logout Pattern
+```typescript
+// SettingsScreen.tsx demonstrates GDPR-compliant logout
+track('User Logged Out', {...});  // Track before clearing
+await flush();                     // Ensure events sent
+reset();                           // Clear all data
+```
+
+## Project Structure
+
+```
+MixpanelStarter/
+├── src/
+│   ├── contexts/
+│   │   └── MixpanelContext.tsx          # Context provider + useMixpanel hook
+│   ├── screens/                         # 3 tab screens
+│   │   ├── OnboardingScreen.tsx         # User identification flow
+│   │   ├── HomeScreen.tsx               # Event tracking patterns
+│   │   └── SettingsScreen.tsx           # Privacy controls
+│   ├── components/                      # Reusable components
+│   │   ├── ErrorBoundary.tsx            # Error boundary wrapper
+│   │   ├── ActionButton.tsx             # Button with loading states
+│   │   └── InfoCard.tsx                 # Key-value display card
+│   ├── types/
+│   │   └── mixpanel.types.ts            # TypeScript interfaces
+│   ├── constants/
+│   │   └── tracking.ts                  # Event names & properties
+│   ├── @types/
+│   │   └── env.d.ts                     # Environment variable types
+│   └── App.tsx                          # Navigation setup
+├── __tests__/
+│   └── MixpanelContext.test.tsx         # Context tests
+├── ios/                                 # iOS native code
+├── android/                             # Android native code
+├── .env.example                         # Environment template
+├── README.md                            # User-facing documentation
+└── INTEGRATION_GUIDE.md                 # Step-by-step integration guide
+```
+
+### File Responsibilities
+
+**MixpanelContext.tsx** (src/contexts/)
+- Initializes Mixpanel SDK on mount
+- Sets default super properties (app version, platform, environment)
+- Provides convenience wrapper methods (track, identify, alias, reset, flush)
+- Manages loading/error states
+- Exports useMixpanel hook
+
+**OnboardingScreen.tsx** (src/screens/)
+- Demonstrates: identify(), alias(), getPeople().set(), setOnce()
+- Shows anonymous-to-identified user flow
+- Displays current distinct ID
+- Guest mode vs signup comparison
+
+**HomeScreen.tsx** (src/screens/)
+- Demonstrates: track(), timeEvent(), registerSuperProperties()
+- Event tracking with rich properties
+- Timed events (video start/complete)
+- Dynamic super properties (dark mode, notifications)
+- Displays current super properties
+
+**SettingsScreen.tsx** (src/screens/)
+- Demonstrates: optIn/OutTracking(), reset(), flush(), hasOptedOutTracking()
+- GDPR compliance controls
+- Data management (reset all data)
+- Manual flush for testing
+- SDK information display
+
+**tracking.ts** (src/constants/)
+- Centralized event names (Events object)
+- Property names (Properties object)
+- Super property keys (SuperProperties object)
+- All constants are `as const` for type safety
+
+## Key Concepts Demonstrated
+
+### 1. Initialization Lifecycle
+```typescript
+// Context handles initialization automatically
+useEffect(() => {
+  const initMixpanel = async () => {
+    const instance = new Mixpanel(token, trackAutomaticEvents, useNative);
+    await instance.init();
+    instance.registerSuperProperties({...});
+    setMixpanel(instance);
+    setIsInitialized(true);
+  };
+  initMixpanel();
+}, [token]);
+```
+
+### 2. Loading State Management
+```typescript
+// Components can check initialization state
+const { isInitialized, isLoading, error } = useMixpanel();
+
+// Disable buttons until ready
+<ActionButton
+  disabled={!isInitialized}
+  onPress={handleAction}
+/>
+```
+
+### 3. Error Handling
+```typescript
+// Context catches initialization errors
+try {
+  await instance.init();
+} catch (err) {
+  setError(err instanceof Error ? err : new Error(String(err)));
+  console.error('Failed to initialize Mixpanel:', error);
+}
+
+// ErrorBoundary catches React errors
+<ErrorBoundary>
+  <MixpanelProvider>
+    {/* app */}
+  </MixpanelProvider>
+</ErrorBoundary>
+```
+
+### 4. TypeScript Strict Mode
+- All files compile without errors
+- Proper typing for all props and state
+- Event/property names are type-safe constants
+- No `any` types except in Record<string, any> for event properties
+
+### 5. Educational Components
+Every screen includes an InfoCard titled "What's Happening?" that explains:
+- Which SDK methods are being used
+- Why you'd use this pattern
+- What data is being sent
+
+## Common Modifications
+
+### Adding a New Event
+
+1. **Define constant** (src/constants/tracking.ts):
+```typescript
+export const Events = {
+  // ... existing events
+  FEATURE_USED: 'Feature Used',
+};
+```
+
+2. **Track in component**:
+```typescript
+const handleFeatureUse = () => {
+  track(Events.FEATURE_USED, {
+    feature_name: 'search',
+    timestamp: new Date().toISOString(),
+  });
+};
+```
+
+### Adding a New Screen
+
+1. **Create screen file** (src/screens/NewScreen.tsx):
+```typescript
+import {useMixpanel} from '../contexts/MixpanelContext';
+import {Events, Properties} from '../constants/tracking';
+
+export const NewScreen = () => {
+  const {track, isInitialized} = useMixpanel();
+
+  useEffect(() => {
+    if (isInitialized) {
+      track(Events.SCREEN_VIEWED, {
+        [Properties.SCREEN_NAME]: 'NewScreen',
+      });
+    }
+  }, [isInitialized, track]);
+
+  // ... component logic
+};
+```
+
+2. **Add to navigation** (src/App.tsx):
+```typescript
+<Tab.Screen
+  name="New"
+  component={NewScreen}
+  options={{
+    tabBarLabel: 'New',
+    tabBarIcon: ({color}) => <Text style={{fontSize: 20, color}}>🎯</Text>,
+  }}
+/>
+```
+
+### Changing Mixpanel Configuration
+
+**In MixpanelProvider** (src/contexts/MixpanelContext.tsx):
+```typescript
+// Change automatic event tracking
+trackAutomaticEvents={false}
+
+// Change native/JS mode
+useNative={false}  // Forces JavaScript implementation
+
+// Modify default super properties
+instance.registerSuperProperties({
+  [SuperProperties.APP_VERSION]: '2.0.0',  // Update version
+  'Custom Property': 'value',               // Add custom property
+});
+```
+
+## Testing Guidelines
+
+### Running Tests
+```bash
+npm test                    # Run all tests
+npm test -- --coverage      # With coverage report
+npm test -- --watch         # Watch mode
+```
+
+### Test Structure
+- **Unit tests**: Components and contexts in isolation
+- **Mock Mixpanel SDK**: Already configured in MixpanelContext.test.tsx
+- **Test initialization**: Verify loading → initialized state transition
+- **Test error handling**: Provider catches and exposes errors
+
+### Writing New Tests
+```typescript
+// Mock Mixpanel SDK
+jest.mock('mixpanel-react-native', () => ({
+  Mixpanel: jest.fn().mockImplementation(() => ({
+    init: jest.fn().mockResolvedValue(undefined),
+    track: jest.fn(),
+    // ... other methods
+  })),
+}));
+
+// Test component with context
+render(
+  <MixpanelProvider token="test-token">
+    <YourComponent />
+  </MixpanelProvider>
+);
+```
+
+## TypeScript Configuration
+
+### Strict Mode Enabled
+```json
+{
+  "compilerOptions": {
+    "strict": true,  // All strict checks enabled
+    "typeRoots": ["./node_modules/@types", "./src/@types"]
+  }
+}
+```
+
+### Type Checking
+```bash
+npx tsc --noEmit  # Check types without emitting files
+```
+
+### Common Type Issues
+- **Environment variables**: Defined in src/@types/env.d.ts
+- **Mixpanel instance**: Can be null before initialization (check isInitialized)
+- **Async methods**: alias() and flush() return Promise<void>
+
+## Debugging
+
+### Enable Logging
+Logging is automatically enabled in development (`__DEV__`):
+```typescript
+if (__DEV__) {
+  instance.setLoggingEnabled(true);
+}
+```
+
+### Console Output
+Look for `[Mixpanel]` prefixed logs:
+- Event tracking confirmations
+- Network requests
+- Error messages
+- Queue status
+
+### Verify Events
+1. **Console**: Check for `[Mixpanel]` logs
+2. **Network**: Use React Native Debugger to see network requests
+3. **Dashboard**: Events appear in Mixpanel Live View (may take 1-2 minutes)
+4. **Distinct ID**: Call `await mixpanel.getDistinctId()` to verify initialization
+
+### Common Issues
+
+**Events not tracked?**
+- Check `isInitialized` is true
+- Verify token is set correctly
+- Check opt-out status: `await hasOptedOutTracking()`
+- Manually flush: `await flush()`
+
+**TypeScript errors?**
+- Clear Metro cache: `npm start -- --reset-cache`
+- Verify all dependencies installed: `npm install`
+- Check tsconfig.json is correct
+
+**Build errors?**
+- iOS: `cd ios && pod install && cd ..`
+- Android: `cd android && ./gradlew clean && cd ..`
+- Clear node_modules: `rm -rf node_modules && npm install`
+
+## Best Practices for Modifications
+
+### DO:
+✅ Use constants for event/property names
+✅ Check `isInitialized` before tracking
+✅ Include timestamps in event properties
+✅ Add "What's Happening?" explanations for new features
+✅ Follow existing file structure and naming conventions
+✅ Update TypeScript types when adding new interfaces
+✅ Test on both iOS and Android
+✅ Keep Context API pattern for Mixpanel access
+
+### DON'T:
+❌ Hardcode event names (use constants)
+❌ Track before initialization
+❌ Use `any` type (use strict TypeScript)
+❌ Skip error handling
+❌ Track PII without user consent
+❌ Over-track (every render/state change)
+❌ Mix navigation patterns (stick to bottom tabs)
+
+## Educational Purpose
+
+This sample app is designed to teach, not just demonstrate. When making changes:
+
+1. **Preserve educational value**: Keep "What's Happening?" cards updated
+2. **Maintain simplicity**: This bridges simple→complex, don't overcomplicate
+3. **Document patterns**: Add comments explaining WHY, not just WHAT
+4. **Keep it copy-pasteable**: Developers should be able to copy patterns directly
+
+## Integration with Parent SDK
+
+This sample lives at: `Samples/MixpanelStarter/`
+
+**SDK dependency**: Uses `file:../..` to reference parent mixpanel-react-native package
+
+**When SDK changes**:
+```bash
+cd Samples/MixpanelStarter
+rm -rf node_modules
+npm install  # Re-links to parent SDK
+```
+
+## Documentation Maintenance
+
+### When to Update Docs
+
+**README.md**: User-facing changes (new features, setup steps, troubleshooting)
+**INTEGRATION_GUIDE.md**: Integration patterns, API changes, best practices
+**CLAUDE.md**: Architecture changes, new patterns, file structure updates
+
+### Documentation Standards
+- Keep examples up-to-date with actual code
+- Include both "why" and "how" explanations
+- Use code snippets from real files (with file paths)
+- Maintain consistent formatting and style
+
+## Version Information
+
+**Created**: 2025
+**React Native Version**: 0.82.1
+**Mixpanel SDK**: 3.1.2
+**Target RN Version**: 0.70+
+
+## AI Assistant Notes
+
+When working with this codebase:
+
+1. **Preserve the educational mission**: This is a learning tool, not just a demo
+2. **Maintain Context API pattern**: Don't switch to Redux/MobX/etc
+3. **Keep TypeScript strict**: No `any` types, proper inference
+4. **Follow existing patterns**: File naming, import order, component structure
+5. **Test changes**: Run `npm test` and `npx tsc --noEmit` before completing
+6. **Update documentation**: README, INTEGRATION_GUIDE, and CLAUDE.md as needed
+
+## Resources
+
+- **Parent SDK**: `../../` (mixpanel-react-native)
+- **Parent CLAUDE.md**: `../../CLAUDE.md`
+- **Mixpanel Docs**: https://docs.mixpanel.com/docs/tracking/advanced/react-native
+- **React Navigation**: https://reactnavigation.org/
+
+Last updated: 2025-05-11

package/Samples/MixpanelStarter/Gemfile

@@ -0,0 +1,16 @@
+source 'https://rubygems.org'
+
+# You may use http://rbenv.org/ or https://rvm.io/ to install and use this version
+ruby ">= 2.6.10"
+
+# Exclude problematic versions of cocoapods and activesupport that causes build failures.
+gem 'cocoapods', '>= 1.13', '!= 1.15.0', '!= 1.15.1'
+gem 'activesupport', '>= 6.1.7.5', '!= 7.1.0'
+gem 'xcodeproj', '< 1.26.0'
+gem 'concurrent-ruby', '< 1.3.4'
+
+# Ruby 3.4.0 has removed some libraries from the standard library.
+gem 'bigdecimal'
+gem 'logger'
+gem 'benchmark'
+gem 'mutex_m'