noboarding 0.1.0-alpha → 1.0.1-beta

package/AI_CUSTOM_SCREEN_GUIDE.md

@@ -0,0 +1,888 @@
+# AI Assistant Guide: Building Custom Screens for Noboarding SDK
+
+> **Purpose:** Copy this entire guide and paste it to your AI coding assistant (Claude Code, Cursor, GitHub Copilot, etc.) when you need to build a custom screen for the Noboarding SDK.
+
+---
+
+## Instructions for AI Assistant
+
+I need you to help me build a custom screen component for the Noboarding SDK. This guide explains how to structure the code, handle data flow between screens, and set up the screen in the dashboard.
+
+---
+
+## Context: How Custom Screens Work
+
+Custom screens are React Native components that integrate into remotely-managed onboarding flows. They:
+- Live in the app code (not on servers)
+- Collect user data during onboarding
+- Pass data to subsequent screens
+- Can access data from previous screens
+- Are positioned in flows via the dashboard
+
+**Data Flow:**
+```
+Screen 1 (SDK or Custom) → collects data → passes to Screen 2
+Screen 2 (Custom) → receives data from Screen 1 → adds more data → passes to Screen 3
+Screen 3 (SDK or Custom) → receives all previous data → continues...
+```
+
+---
+
+## Part 1: Custom Screen Component Structure
+
+### Required Imports
+
+```typescript
+import React, { useState, useEffect } from 'react';
+import { View, Text, Button, StyleSheet } from 'react-native';
+import type { CustomScreenProps } from 'noboarding';
+```
+
+### Component Props Interface
+
+Every custom screen receives these props from the SDK:
+
+```typescript
+interface CustomScreenProps {
+  // Analytics tracking
+  analytics: {
+    track: (event: string, properties?: Record<string, any>) => void;
+  };
+
+  // Navigation
+  onNext: () => void;           // Move to next screen
+  onBack?: () => void;          // Move to previous screen (undefined on first screen)
+  onSkip?: () => void;          // Skip this screen (optional)
+
+  // Data flow
+  data?: Record<string, any>;   // Data from PREVIOUS screens (read-only)
+  onDataUpdate?: (newData: Record<string, any>) => void;  // Add YOUR data
+
+  // Preview mode
+  preview?: boolean;            // True when rendering in dashboard
+}
+```
+
+### Basic Component Template
+
+```typescript
+export const MyCustomScreen: React.FC<CustomScreenProps> = ({
+  analytics,
+  onNext,
+  onSkip,
+  preview,
+  data,           // Data from previous screens
+  onDataUpdate,   // Function to add your data
+}) => {
+  // 1. Local state for THIS screen's data
+  const [myData, setMyData] = useState({
+    // Initialize with default values
+  });
+
+  // 2. Track screen view on mount
+  useEffect(() => {
+    analytics.track('screen_viewed', {
+      screen_id: 'my_custom_screen',
+      screen_type: 'custom'
+    });
+  }, []);
+
+  // 3. Handle continue/next
+  const handleContinue = () => {
+    // Update collected data with THIS screen's data
+    onDataUpdate?.({
+      // Add your screen's data here
+      ...myData,
+    });
+
+    // Track completion
+    analytics.track('screen_completed', {
+      screen_id: 'my_custom_screen',
+    });
+
+    // Navigate to next screen
+    onNext();
+  };
+
+  // 4. Preview mode (for dashboard)
+  if (preview) {
+    return (
+      <View style={styles.previewContainer}>
+        <Text style={styles.previewText}>Preview: My Custom Screen</Text>
+        <Button title="Continue" onPress={onNext} />
+      </View>
+    );
+  }
+
+  // 5. Real implementation
+  return (
+    <View style={styles.container}>
+      {/* Access data from PREVIOUS screens */}
+      {data?.userName && (
+        <Text>Welcome back, {data.userName}!</Text>
+      )}
+
+      {/* Your screen UI here */}
+
+      <Button title="Continue" onPress={handleContinue} />
+      {onSkip && (
+        <Button title="Skip" onPress={onSkip} color="#666" />
+      )}
+    </View>
+  );
+};
+```
+
+---
+
+## Part 2: Data Flow Between Screens
+
+### Example: Multi-Screen Data Collection
+
+**Screen 1: Name Collection (Custom)**
+
+```typescript
+export const NameScreen: React.FC<CustomScreenProps> = ({
+  analytics,
+  onNext,
+  data,
+  onDataUpdate,
+}) => {
+  const [name, setName] = useState('');
+
+  const handleContinue = () => {
+    // Add THIS screen's data
+    onDataUpdate?.({
+      userName: name,
+      nameCollectedAt: new Date().toISOString(),
+    });
+
+    analytics.track('name_collected', { name });
+    onNext();
+  };
+
+  return (
+    <View>
+      <TextInput
+        placeholder="Enter your name"
+        value={name}
+        onChangeText={setName}
+      />
+      <Button title="Continue" onPress={handleContinue} />
+    </View>
+  );
+};
+```
+
+**Screen 2: Age Collection (Custom)**
+
+```typescript
+export const AgeScreen: React.FC<CustomScreenProps> = ({
+  analytics,
+  onNext,
+  data,           // Contains: { userName, nameCollectedAt }
+  onDataUpdate,
+}) => {
+  const [age, setAge] = useState('');
+
+  const handleContinue = () => {
+    // Add THIS screen's data
+    onDataUpdate?.({
+      userAge: parseInt(age),
+      ageCollectedAt: new Date().toISOString(),
+    });
+
+    analytics.track('age_collected', { age });
+    onNext();
+  };
+
+  return (
+    <View>
+      {/* Access data from previous screen */}
+      <Text>Hi {data?.userName}! What's your age?</Text>
+
+      <TextInput
+        placeholder="Enter your age"
+        value={age}
+        onChangeText={setAge}
+        keyboardType="numeric"
+      />
+      <Button title="Continue" onPress={handleContinue} />
+    </View>
+  );
+};
+```
+
+**Screen 3: Summary (Custom)**
+
+```typescript
+export const SummaryScreen: React.FC<CustomScreenProps> = ({
+  analytics,
+  onNext,
+  data,  // Contains: { userName, nameCollectedAt, userAge, ageCollectedAt }
+}) => {
+  return (
+    <View>
+      <Text>Summary:</Text>
+      <Text>Name: {data?.userName}</Text>
+      <Text>Age: {data?.userAge}</Text>
+
+      <Button title="Confirm" onPress={onNext} />
+    </View>
+  );
+};
+```
+
+**Final onComplete Handler (in App.tsx)**
+
+```typescript
+<OnboardingFlow
+  // Dual API keys for automatic environment detection
+  testKey="nb_test_..."
+  productionKey="nb_live_..."
+  // SDK auto-detects __DEV__ and uses appropriate key
+
+  customComponents={{
+    NameScreen,
+    AgeScreen,
+    SummaryScreen,
+  }}
+  onComplete={(userData) => {
+    // userData contains ALL collected data:
+    console.log(userData);
+    // {
+    //   userName: "John",
+    //   nameCollectedAt: "2025-02-20...",
+    //   userAge: 25,
+    //   ageCollectedAt: "2025-02-20...",
+    //   _variables: { ... }
+    // }
+  }}
+/>
+```
+
+---
+
+## Part 3: Common Patterns
+
+### Pattern 1: Form with Validation
+
+```typescript
+export const FormScreen: React.FC<CustomScreenProps> = ({
+  analytics,
+  onNext,
+  onDataUpdate,
+}) => {
+  const [formData, setFormData] = useState({
+    email: '',
+    phone: '',
+  });
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  const validate = () => {
+    const newErrors: Record<string, string> = {};
+
+    if (!formData.email.match(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)) {
+      newErrors.email = 'Invalid email';
+    }
+
+    if (!formData.phone.match(/^\d{10}$/)) {
+      newErrors.phone = 'Phone must be 10 digits';
+    }
+
+    setErrors(newErrors);
+    return Object.keys(newErrors).length === 0;
+  };
+
+  const handleSubmit = () => {
+    if (validate()) {
+      onDataUpdate?.(formData);
+      analytics.track('form_submitted', { valid: true });
+      onNext();
+    } else {
+      analytics.track('form_validation_failed', { errors: Object.keys(errors) });
+    }
+  };
+
+  return (
+    <View>
+      <TextInput
+        placeholder="Email"
+        value={formData.email}
+        onChangeText={(email) => setFormData({ ...formData, email })}
+      />
+      {errors.email && <Text style={styles.error}>{errors.email}</Text>}
+
+      <TextInput
+        placeholder="Phone"
+        value={formData.phone}
+        onChangeText={(phone) => setFormData({ ...formData, phone })}
+      />
+      {errors.phone && <Text style={styles.error}>{errors.phone}</Text>}
+
+      <Button title="Continue" onPress={handleSubmit} />
+    </View>
+  );
+};
+```
+
+### Pattern 2: Multi-Select Options
+
+```typescript
+export const PreferencesScreen: React.FC<CustomScreenProps> = ({
+  analytics,
+  onNext,
+  data,
+  onDataUpdate,
+}) => {
+  const [selectedPreferences, setSelectedPreferences] = useState<string[]>([]);
+
+  const options = ['Option A', 'Option B', 'Option C', 'Option D'];
+
+  const togglePreference = (option: string) => {
+    if (selectedPreferences.includes(option)) {
+      setSelectedPreferences(selectedPreferences.filter(p => p !== option));
+    } else {
+      setSelectedPreferences([...selectedPreferences, option]);
+    }
+  };
+
+  const handleContinue = () => {
+    onDataUpdate?.({
+      preferences: selectedPreferences,
+      preferencesCount: selectedPreferences.length,
+    });
+
+    analytics.track('preferences_selected', {
+      count: selectedPreferences.length,
+      selections: selectedPreferences,
+    });
+
+    onNext();
+  };
+
+  return (
+    <View>
+      <Text>Select your preferences:</Text>
+
+      {options.map(option => (
+        <TouchableOpacity
+          key={option}
+          onPress={() => togglePreference(option)}
+          style={[
+            styles.option,
+            selectedPreferences.includes(option) && styles.optionSelected
+          ]}
+        >
+          <Text>{option}</Text>
+          {selectedPreferences.includes(option) && <Text>✓</Text>}
+        </TouchableOpacity>
+      ))}
+
+      <Button
+        title="Continue"
+        onPress={handleContinue}
+        disabled={selectedPreferences.length === 0}
+      />
+    </View>
+  );
+};
+```
+
+### Pattern 3: API Call with Data from Previous Screen
+
+```typescript
+export const ProfileSetupScreen: React.FC<CustomScreenProps> = ({
+  analytics,
+  onNext,
+  data,  // Data from previous screens
+  onDataUpdate,
+}) => {
+  const [loading, setLoading] = useState(false);
+
+  const createProfile = async () => {
+    setLoading(true);
+    analytics.track('profile_creation_started');
+
+    try {
+      // Use data from previous screens
+      const response = await fetch('https://your-api.com/profile', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          name: data?.userName,
+          age: data?.userAge,
+          email: data?.email,
+          preferences: data?.preferences,
+        }),
+      });
+
+      const result = await response.json();
+
+      // Add API response to collected data
+      onDataUpdate?.({
+        profileId: result.id,
+        profileCreated: true,
+        profileCreatedAt: new Date().toISOString(),
+      });
+
+      analytics.track('profile_created', { profileId: result.id });
+      onNext();
+    } catch (error: any) {
+      analytics.track('profile_creation_failed', { error: error.message });
+      Alert.alert('Error', 'Failed to create profile. Please try again.');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <View>
+      <Text>Creating profile for {data?.userName}...</Text>
+      <Button
+        title="Create Profile"
+        onPress={createProfile}
+        disabled={loading}
+      />
+      {loading && <ActivityIndicator />}
+    </View>
+  );
+};
+```
+
+### Pattern 4: Conditional Logic Based on Previous Data
+
+```typescript
+export const ConditionalScreen: React.FC<CustomScreenProps> = ({
+  analytics,
+  onNext,
+  data,
+  onDataUpdate,
+}) => {
+  // Show different UI based on previous data
+  const isPremiumUser = data?.userAge && data.userAge > 25;
+
+  if (isPremiumUser) {
+    return (
+      <View>
+        <Text>Premium Experience</Text>
+        <Text>Welcome {data?.userName}! You qualify for premium features.</Text>
+        <Button
+          title="Continue"
+          onPress={() => {
+            onDataUpdate?.({ userTier: 'premium' });
+            onNext();
+          }}
+        />
+      </View>
+    );
+  }
+
+  return (
+    <View>
+      <Text>Standard Experience</Text>
+      <Text>Welcome {data?.userName}!</Text>
+      <Button
+        title="Continue"
+        onPress={() => {
+          onDataUpdate?.({ userTier: 'standard' });
+          onNext();
+        }}
+      />
+    </View>
+  );
+};
+```
+
+---
+
+## Part 4: Analytics Best Practices
+
+### Track All Key Events
+
+```typescript
+// Screen lifecycle
+useEffect(() => {
+  analytics.track('screen_viewed', {
+    screen_id: 'my_screen',
+    screen_type: 'custom',
+  });
+
+  return () => {
+    analytics.track('screen_exited', {
+      screen_id: 'my_screen',
+    });
+  };
+}, []);
+
+// User interactions
+analytics.track('button_clicked', { button: 'submit' });
+analytics.track('input_focused', { field: 'email' });
+analytics.track('option_selected', { option: 'premium' });
+
+// Completion
+analytics.track('screen_completed', {
+  screen_id: 'my_screen',
+  data_collected: true,
+});
+
+// Errors
+analytics.track('error_occurred', {
+  error_type: 'validation',
+  error_message: 'Invalid email',
+});
+```
+
+---
+
+## Part 5: Setting Up Custom Screens in Dashboard
+
+### Step 1: Register Component in App
+
+```typescript
+// App.tsx
+import { OnboardingFlow } from 'noboarding';
+import { NameScreen } from './screens/NameScreen';
+import { AgeScreen } from './screens/AgeScreen';
+import { PreferencesScreen } from './screens/PreferencesScreen';
+
+<OnboardingFlow
+  // Use dual API keys for automatic environment detection
+  testKey="nb_test_your_test_key"
+  productionKey="nb_live_your_production_key"
+  // The SDK automatically uses testKey when __DEV__ is true
+  // and productionKey in production builds
+
+  customComponents={{
+    NameScreen: NameScreen,           // Component name MUST match exactly
+    AgeScreen: AgeScreen,             // Case-sensitive!
+    PreferencesScreen: PreferencesScreen,
+  }}
+  onComplete={(userData) => {
+    console.log('All collected data:', userData);
+  }}
+/>
+```
+
+### Step 2: Add to Dashboard Flow
+
+1. **Log in to Noboarding Dashboard**
+2. **Go to Flows** and select or create a flow
+3. **Click "Add Custom Screen"**
+4. **Enter Component Name:** (must match EXACTLY what you registered)
+   - Example: `NameScreen`
+   - ❌ Wrong: `nameScreen`, `name_screen`, `NameScreenComponent`
+   - ✅ Correct: `NameScreen`
+5. **Add Description:** "Collects user's name"
+6. **Position in Flow:** Drag to desired position
+7. **Save Draft**
+
+### Step 3: Flow Order Example
+
+```
+Dashboard Flow Builder:
+┌─────────────────────────────────────┐
+│ 1. Welcome Screen (SDK)             │
+│ 2. NameScreen (Custom)              │ ← Your custom screen
+│ 3. AgeScreen (Custom)               │ ← Your custom screen
+│ 4. Feature Tour (SDK)               │
+│ 5. PreferencesScreen (Custom)       │ ← Your custom screen
+│ 6. Complete (SDK)                   │
+└─────────────────────────────────────┘
+```
+
+### Step 4: Test Locally
+
+```bash
+npm start
+# Test in development mode
+# Navigate through onboarding
+# Check console for collected data
+```
+
+### Step 5: Deploy & Publish
+
+1. Test locally with Test API Key (development mode)
+2. In dashboard: **Publish → Publish for Testing**
+3. Build production app
+4. Submit to App Store / Google Play
+5. **WAIT for approval**
+6. **After app is live:** In dashboard, **Publish → Publish to Production**
+
+**Note:** Test and Production environments are separate. You can safely test changes using the Test API Key before rolling them out to production users with the Production API Key.
+
+---
+
+## Part 6: Complete Example - Multi-Step Form
+
+Here's a complete example showing data flow across 3 custom screens:
+
+```typescript
+// screens/Step1EmailScreen.tsx
+export const Step1EmailScreen: React.FC<CustomScreenProps> = ({
+  analytics,
+  onNext,
+  preview,
+  onDataUpdate,
+}) => {
+  const [email, setEmail] = useState('');
+
+  useEffect(() => {
+    analytics.track('screen_viewed', { screen_id: 'step1_email' });
+  }, []);
+
+  const handleContinue = () => {
+    onDataUpdate?.({
+      email: email,
+      emailCollectedAt: new Date().toISOString(),
+    });
+    analytics.track('email_collected');
+    onNext();
+  };
+
+  if (preview) {
+    return (
+      <View style={styles.preview}>
+        <Text>📧 Email Collection Screen</Text>
+        <Button title="Continue" onPress={onNext} />
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>What's your email?</Text>
+      <TextInput
+        style={styles.input}
+        placeholder="email@example.com"
+        value={email}
+        onChangeText={setEmail}
+        keyboardType="email-address"
+        autoCapitalize="none"
+      />
+      <Button
+        title="Continue"
+        onPress={handleContinue}
+        disabled={!email}
+      />
+    </View>
+  );
+};
+
+// screens/Step2GoalsScreen.tsx
+export const Step2GoalsScreen: React.FC<CustomScreenProps> = ({
+  analytics,
+  onNext,
+  data,  // Contains: { email, emailCollectedAt }
+  preview,
+  onDataUpdate,
+}) => {
+  const [selectedGoals, setSelectedGoals] = useState<string[]>([]);
+
+  useEffect(() => {
+    analytics.track('screen_viewed', {
+      screen_id: 'step2_goals',
+      user_email: data?.email
+    });
+  }, []);
+
+  const goals = ['Fitness', 'Nutrition', 'Sleep', 'Mindfulness'];
+
+  const toggleGoal = (goal: string) => {
+    if (selectedGoals.includes(goal)) {
+      setSelectedGoals(selectedGoals.filter(g => g !== goal));
+    } else {
+      setSelectedGoals([...selectedGoals, goal]);
+    }
+  };
+
+  const handleContinue = () => {
+    onDataUpdate?.({
+      goals: selectedGoals,
+      goalsCount: selectedGoals.length,
+    });
+    analytics.track('goals_selected', { count: selectedGoals.length });
+    onNext();
+  };
+
+  if (preview) {
+    return (
+      <View style={styles.preview}>
+        <Text>🎯 Goals Selection Screen</Text>
+        <Button title="Continue" onPress={onNext} />
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>
+        Hi {data?.email?.split('@')[0]}! What are your goals?
+      </Text>
+
+      {goals.map(goal => (
+        <TouchableOpacity
+          key={goal}
+          onPress={() => toggleGoal(goal)}
+          style={[
+            styles.goalOption,
+            selectedGoals.includes(goal) && styles.goalSelected
+          ]}
+        >
+          <Text>{goal}</Text>
+          {selectedGoals.includes(goal) && <Text>✓</Text>}
+        </TouchableOpacity>
+      ))}
+
+      <Button
+        title="Continue"
+        onPress={handleContinue}
+        disabled={selectedGoals.length === 0}
+      />
+    </View>
+  );
+};
+
+// screens/Step3SummaryScreen.tsx
+export const Step3SummaryScreen: React.FC<CustomScreenProps> = ({
+  analytics,
+  onNext,
+  data,  // Contains: { email, emailCollectedAt, goals, goalsCount }
+  preview,
+}) => {
+  useEffect(() => {
+    analytics.track('screen_viewed', { screen_id: 'step3_summary' });
+  }, []);
+
+  if (preview) {
+    return (
+      <View style={styles.preview}>
+        <Text>📋 Summary Screen</Text>
+        <Button title="Continue" onPress={onNext} />
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Summary</Text>
+
+      <View style={styles.summaryCard}>
+        <Text style={styles.label}>Email:</Text>
+        <Text style={styles.value}>{data?.email}</Text>
+      </View>
+
+      <View style={styles.summaryCard}>
+        <Text style={styles.label}>Goals ({data?.goalsCount}):</Text>
+        {data?.goals?.map((goal: string) => (
+          <Text key={goal} style={styles.value}>• {goal}</Text>
+        ))}
+      </View>
+
+      <Button title="Complete Setup" onPress={onNext} />
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    padding: 20,
+    backgroundColor: '#fff',
+  },
+  preview: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+    padding: 20,
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: 'bold',
+    marginBottom: 20,
+  },
+  input: {
+    borderWidth: 1,
+    borderColor: '#ccc',
+    borderRadius: 8,
+    padding: 12,
+    fontSize: 16,
+    marginBottom: 20,
+  },
+  goalOption: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    padding: 16,
+    borderWidth: 1,
+    borderColor: '#ccc',
+    borderRadius: 8,
+    marginBottom: 12,
+  },
+  goalSelected: {
+    borderColor: '#007AFF',
+    backgroundColor: '#E3F2FD',
+  },
+  summaryCard: {
+    padding: 16,
+    backgroundColor: '#f5f5f5',
+    borderRadius: 8,
+    marginBottom: 16,
+  },
+  label: {
+    fontSize: 14,
+    color: '#666',
+    marginBottom: 4,
+  },
+  value: {
+    fontSize: 16,
+    color: '#000',
+  },
+});
+```
+
+**Register in App.tsx:**
+
+```typescript
+<OnboardingFlow
+  // Dual API keys - SDK auto-detects environment
+  testKey="nb_test_..."
+  productionKey="nb_live_..."
+
+  customComponents={{
+    Step1EmailScreen,
+    Step2GoalsScreen,
+    Step3SummaryScreen,
+  }}
+  onComplete={(userData) => {
+    console.log(userData);
+    // {
+    //   email: "john@example.com",
+    //   emailCollectedAt: "2025-02-20...",
+    //   goals: ["Fitness", "Nutrition"],
+    //   goalsCount: 2,
+    //   _variables: { ... }
+    // }
+  }}
+/>
+```
+
+---
+
+## Summary Checklist
+
+When building a custom screen, ensure you:
+
+- [ ] Import `CustomScreenProps` from 'noboarding'
+- [ ] Use all required props: `analytics`, `onNext`, `data`, `onDataUpdate`
+- [ ] Track `screen_viewed` on mount
+- [ ] Implement `preview` mode for dashboard
+- [ ] Call `onDataUpdate()` to add your data before `onNext()`
+- [ ] Track `screen_completed` before navigating
+- [ ] Access previous data via `data` prop
+- [ ] Register component in `customComponents` with EXACT name
+- [ ] Add to dashboard with matching component name
+- [ ] Test data flow across multiple screens
+
+---
+
+**Now you're ready to build custom screens!** Ask me any questions if you need clarification on any part of this guide.

package/README.md

@@ -14,6 +14,7 @@ yarn add noboarding
 - **[AI Setup](./SETUP_GUIDE.md#ai-setup)** - Copy/paste instructions for your AI coding assistant (Claude Code, Cursor, etc.)
 - **[Manual Setup](./SETUP_GUIDE.md#normal-setup)** - Step-by-step instructions
 - **[RevenueCat Integration](./REVENUECAT_SETUP.md)** - Detailed RevenueCat paywall guide
+- **[AI Custom Screen Guide](./AI_CUSTOM_SCREEN_GUIDE.md)** - Complete guide for building custom screens with data flow (for AI assistants)
 
 ## Quick Start
 
@@ -26,7 +27,14 @@ function App() {
   if (showOnboarding) {
     return (
       <OnboardingFlow
-        apiKey="sk_live_your_api_key_here"
+        // Recommended: Use dual keys for automatic environment detection
+        testKey="nb_test_your_test_key_here"
+        productionKey="nb_live_your_production_key_here"
+        // The SDK automatically uses testKey in __DEV__ and productionKey in production
+
+        // Alternative: Legacy single key (still supported)
+        // apiKey="nb_test_your_api_key_here"
+
         onComplete={(userData) => {
           console.log('Collected data:', userData);
           setShowOnboarding(false);
@@ -47,6 +55,14 @@ function App() {
 }
 ```
 
+### API Keys
+
+You'll find two API keys in your dashboard:
+- **Test Key** (`nb_test_...`) - Used for development and testing
+- **Production Key** (`nb_live_...`) - Used for production builds
+
+The SDK automatically detects your environment using React Native's `__DEV__` flag and uses the appropriate key.
+
 ## How It Works
 
 1. The SDK fetches your onboarding configuration from Supabase at runtime
@@ -240,6 +256,7 @@ interface CustomScreenProps {
     track: (event: string, properties?: Record<string, any>) => void;
   };
   onNext: () => void;
+  onBack?: () => void;  // Navigate to previous screen (undefined on first screen)
   onSkip?: () => void;
   preview?: boolean;  // True when rendering in dashboard preview
   data?: Record<string, any>;  // Previously collected user data
@@ -426,7 +443,7 @@ useEffect(() => {
 - ✅ Handle errors gracefully with user-friendly messages
 - ✅ Call `onNext()` when screen is complete
 
-For more details, see [Custom Screens Guide](./cusomte_screens.md).
+For more details, see [AI Custom Screen Guide](./AI_CUSTOM_SCREEN_GUIDE.md).
 
 ## API
 
@@ -496,6 +513,8 @@ import { API, AnalyticsManager } from 'noboarding';
 
 ## Development
 
+### Building the SDK
+
 The TestApp imports the SDK from the compiled `lib/` directory (`"main": "lib/index.js"`), not from `src/` directly. After making any changes to files in `sdk/src/`, you must rebuild before testing:
 
 ```bash
@@ -505,6 +524,63 @@ npm run build
 
 Then restart the TestApp. If you skip this step, the TestApp will still be running the old compiled code and your changes won't take effect.
 
+### Dashboard Preview Integration
+
+The dashboard uses **local copies** of SDK source files for the preview feature. When you modify SDK source files, they need to be synced to the dashboard.
+
+**Why copies?** Next.js/Turbopack doesn't support importing from external directories with the react-native-web setup, so the dashboard maintains local copies in `dashboard/lib/sdk/`.
+
+#### Files That Need Syncing
+
+When you modify these SDK files:
+- `src/types.ts` → Auto-synced to `dashboard/lib/sdk/types.ts`
+- `src/variableUtils.ts` → Auto-synced to `dashboard/lib/sdk/variableUtils.ts`
+- `src/components/ElementRenderer.tsx` → ⚠️ **NOT auto-synced** (dashboard has web-specific modifications)
+
+**ElementRenderer Special Case:**
+
+The dashboard copy of `ElementRenderer.tsx` has web-specific modifications for icon support:
+- Uses `react-icons` instead of `@expo/vector-icons`
+- Renders real icons in preview (Feather, Material, Ionicons, FontAwesome)
+- Gradients fall back to solid colors
+
+**If you modify ElementRenderer.tsx significantly:**
+1. Run `npm run sync:full` from project root to copy it
+2. Manually re-add web icon imports and logic (check git diff to see what changed)
+
+#### Syncing Methods
+
+**Manual sync (run when needed):**
+```bash
+# From project root
+npm run sync
+```
+
+**Auto-sync during development:**
+```bash
+# From project root
+npm run sync:watch
+```
+
+This watches SDK files and automatically copies changes to the dashboard when you save.
+
+**Full development mode:**
+```bash
+# From project root - starts dashboard + auto-sync
+npm run dev
+```
+
+This command:
+1. Syncs SDK files to dashboard
+2. Starts file watcher for auto-sync
+3. Starts dashboard dev server
+
+#### Important Notes
+
+- ⚠️ **Dashboard preview uses copies** - Changes to SDK files won't appear in dashboard preview until synced
+- ✅ **Mobile app uses npm package** - TestApp uses the built SDK from `lib/`, requires `npm run build`
+- 🔄 **Keep in sync** - Run `npm run sync:watch` while developing SDK to keep dashboard preview accurate
+
 ## Requirements
 
 - React Native >= 0.60.0

package/lib/OnboardingFlow.js

@@ -47,7 +47,31 @@ const generateUserId = () => {
 const generateSessionId = () => {
     return `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
 };
-const OnboardingFlow = ({ apiKey, onComplete, onSkip, baseUrl, initialVariables, customComponents, onUserIdGenerated, }) => {
+// Detect environment: true in dev/Expo, false in production builds
+const detectEnvironment = () => {
+    if (__DEV__)
+        return 'test';
+    return 'production';
+};
+const OnboardingFlow = ({ apiKey, testKey, productionKey, onComplete, onSkip, baseUrl, initialVariables, customComponents, onUserIdGenerated, }) => {
+    // Determine which API key to use
+    const getApiKey = () => {
+        // If dual keys provided, use environment detection
+        if (testKey && productionKey) {
+            const env = detectEnvironment();
+            return env === 'test' ? testKey : productionKey;
+        }
+        // If only one dual key provided, use it
+        if (testKey)
+            return testKey;
+        if (productionKey)
+            return productionKey;
+        // Fallback to legacy single key
+        if (apiKey)
+            return apiKey;
+        throw new Error('Noboarding SDK: No API key provided. Please provide either apiKey, or both testKey and productionKey.');
+    };
+    const activeApiKey = getApiKey();
     const [loading, setLoading] = (0, react_1.useState)(true);
     const [error, setError] = (0, react_1.useState)(null);
     const [screens, setScreens] = (0, react_1.useState)([]);
@@ -75,8 +99,8 @@ const OnboardingFlow = ({ apiKey, onComplete, onSkip, baseUrl, initialVariables,
         try {
             setLoading(true);
             setError(null);
-            // Initialize API client
-            const api = new api_1.API(apiKey, baseUrl);
+            // Initialize API client with detected API key
+            const api = new api_1.API(activeApiKey, baseUrl);
             apiRef.current = api;
             // Initialize analytics
             const analytics = new analytics_1.AnalyticsManager(api, userIdRef.current, sessionIdRef.current);
@@ -86,7 +110,10 @@ const OnboardingFlow = ({ apiKey, onComplete, onSkip, baseUrl, initialVariables,
             // Fetch configuration
             const configResponse = await api.getConfig();
             // Backward compatibility: normalize legacy 'custom_screen' (with elements) to 'noboard_screen'
-            const normalizedScreens = configResponse.config.screens.map(s => (Object.assign(Object.assign({}, s), { type: (s.type === 'custom_screen' && s.elements) ? 'noboard_screen' : s.type })));
+            const normalizedScreens = configResponse.config.screens
+                .map(s => (Object.assign(Object.assign({}, s), { type: (s.type === 'custom_screen' && s.elements) ? 'noboard_screen' : s.type })))
+                // Filter out hidden screens (dashboard show/hide feature)
+                .filter(s => !s.hidden);
             setScreens(normalizedScreens);
             setLoading(false);
         }
@@ -109,6 +136,12 @@ const OnboardingFlow = ({ apiKey, onComplete, onSkip, baseUrl, initialVariables,
             setCurrentIndex((prev) => prev + 1);
         }
     };
+    const handleBack = () => {
+        // Navigate to previous screen (only if not on first screen)
+        if (currentIndex > 0) {
+            setCurrentIndex((prev) => prev - 1);
+        }
+    };
     const handleSkipScreen = () => {
         // Move to next screen or complete
         if (currentIndex >= screens.length - 1) {
@@ -201,7 +234,7 @@ const OnboardingFlow = ({ apiKey, onComplete, onSkip, baseUrl, initialVariables,
         </react_native_1.View>);
         }
         return (<react_native_1.View style={styles.container}>
-        <CustomComponent analytics={analyticsRef.current} onNext={() => handleNext()} onSkip={onSkip ? handleSkipAll : undefined} data={collectedData} onDataUpdate={(newData) => setCollectedData(prev => (Object.assign(Object.assign({}, prev), newData)))}/>
+        <CustomComponent analytics={analyticsRef.current} onNext={() => handleNext()} onBack={currentIndex > 0 ? handleBack : undefined} onSkip={onSkip ? handleSkipAll : undefined} data={collectedData} onDataUpdate={(newData) => setCollectedData(prev => (Object.assign(Object.assign({}, prev), newData)))}/>
       </react_native_1.View>);
     }
     // Unknown screen type fallback

package/lib/components/ElementRenderer.js

@@ -170,7 +170,7 @@ const ElementRenderer = ({ elements, analytics, screenId, onNavigate, onDismiss,
 };
 exports.ElementRenderer = ElementRenderer;
 const RenderNode = ({ element, toggledIds, groupSelections, onAction, variables }) => {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3, _4, _5;
     // Variable-based conditions — hide element if condition is not met
     if ((_a = element.conditions) === null || _a === void 0 ? void 0 : _a.show_if) {
         const shouldShow = (0, variableUtils_1.evaluateCondition)(element.conditions.show_if, variables);
@@ -204,7 +204,14 @@ const RenderNode = ({ element, toggledIds, groupSelections, onAction, variables
     const wrapWithAction = (content) => {
         if (!hasAction)
             return content;
-        return (<react_native_1.TouchableOpacity key={element.id} activeOpacity={0.7} onPress={() => onAction(element)}>
+        // Extract width/alignment styles that should apply to TouchableOpacity wrapper
+        // This ensures buttons with width: "100%" don't shrink to content
+        const wrapperStyle = {};
+        if (style.width)
+            wrapperStyle.width = style.width;
+        if (style.alignSelf)
+            wrapperStyle.alignSelf = style.alignSelf;
+        return (<react_native_1.TouchableOpacity key={element.id} activeOpacity={0.7} onPress={() => onAction(element)} style={wrapperStyle}>
         {content}
       </react_native_1.TouchableOpacity>);
     };
@@ -340,7 +347,14 @@ const RenderNode = ({ element, toggledIds, groupSelections, onAction, variables
             </react_native_1.Text>)}
         </react_native_1.View>);
         case 'input':
-            return (<react_native_1.TextInput style={[style, { borderWidth: 1, borderColor: '#E5E5E5' }]} placeholder={((_0 = element.props) === null || _0 === void 0 ? void 0 : _0.placeholder) || 'Enter text...'} keyboardType={getKeyboardType((_1 = element.props) === null || _1 === void 0 ? void 0 : _1.type)} secureTextEntry={((_2 = element.props) === null || _2 === void 0 ? void 0 : _2.type) === 'password'} autoCapitalize={((_3 = element.props) === null || _3 === void 0 ? void 0 : _3.type) === 'email' ? 'none' : 'sentences'}/>);
+            // Only apply default border if borderWidth is not explicitly defined (including 0)
+            const inputStyle = style;
+            const defaultInputStyle = {};
+            if (((_0 = element.style) === null || _0 === void 0 ? void 0 : _0.borderWidth) === undefined && ((_1 = element.style) === null || _1 === void 0 ? void 0 : _1.borderColor) === undefined) {
+                defaultInputStyle.borderWidth = 1;
+                defaultInputStyle.borderColor = '#E5E5E5';
+            }
+            return (<react_native_1.TextInput style={[defaultInputStyle, inputStyle]} placeholder={((_2 = element.props) === null || _2 === void 0 ? void 0 : _2.placeholder) || 'Enter text...'} keyboardType={getKeyboardType((_3 = element.props) === null || _3 === void 0 ? void 0 : _3.type)} secureTextEntry={((_4 = element.props) === null || _4 === void 0 ? void 0 : _4.type) === 'password'} autoCapitalize={((_5 = element.props) === null || _5 === void 0 ? void 0 : _5.type) === 'email' ? 'none' : 'sentences'}/>);
         case 'spacer':
             return <react_native_1.View style={style || { flex: 1 }}/>;
         case 'divider':

package/lib/types.d.ts

@@ -6,6 +6,7 @@ export interface ScreenConfig {
     props: Record<string, any>;
     elements?: ElementNode[];
     custom_component_name?: string;
+    hidden?: boolean;
 }
 export type ElementType = 'vstack' | 'hstack' | 'zstack' | 'scrollview' | 'text' | 'image' | 'video' | 'lottie' | 'icon' | 'input' | 'spacer' | 'divider';
 export interface ElementNode {
@@ -169,13 +170,16 @@ export interface CustomScreenProps {
         track: (event: string, properties?: Record<string, any>) => void;
     };
     onNext: () => void;
+    onBack?: () => void;
     onSkip?: () => void;
     preview?: boolean;
     data?: Record<string, any>;
     onDataUpdate?: (data: Record<string, any>) => void;
 }
 export interface OnboardingFlowProps {
-    apiKey: string;
+    testKey?: string;
+    productionKey?: string;
+    apiKey?: string;
     onComplete: (data?: Record<string, any>) => void;
     onSkip?: () => void;
     baseUrl?: string;

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "noboarding",
-  "version": "0.1.0-alpha",
+  "version": "1.0.1-beta",
   "description": "React Native SDK for remote onboarding flow management",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*"
+  },
   "scripts": {
     "build": "tsc",
-    "watch": "tsc --watch",
-    "prepare": "npm run build"
+    "watch": "tsc --watch"
   },
   "keywords": [
     "react-native",

package/src/OnboardingFlow.tsx

@@ -15,8 +15,16 @@ const generateSessionId = (): string => {
   return `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
 };
 
+// Detect environment: true in dev/Expo, false in production builds
+const detectEnvironment = (): 'test' | 'production' => {
+  if (__DEV__) return 'test';
+  return 'production';
+};
+
 export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   apiKey,
+  testKey,
+  productionKey,
   onComplete,
   onSkip,
   baseUrl,
@@ -24,6 +32,25 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   customComponents,
   onUserIdGenerated,
 }) => {
+  // Determine which API key to use
+  const getApiKey = (): string => {
+    // If dual keys provided, use environment detection
+    if (testKey && productionKey) {
+      const env = detectEnvironment();
+      return env === 'test' ? testKey : productionKey;
+    }
+
+    // If only one dual key provided, use it
+    if (testKey) return testKey;
+    if (productionKey) return productionKey;
+
+    // Fallback to legacy single key
+    if (apiKey) return apiKey;
+
+    throw new Error('Noboarding SDK: No API key provided. Please provide either apiKey, or both testKey and productionKey.');
+  };
+
+  const activeApiKey = getApiKey();
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [screens, setScreens] = useState<ScreenConfig[]>([]);
@@ -57,8 +84,8 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
       setLoading(true);
       setError(null);
 
-      // Initialize API client
-      const api = new API(apiKey, baseUrl);
+      // Initialize API client with detected API key
+      const api = new API(activeApiKey, baseUrl);
       apiRef.current = api;
 
       // Initialize analytics
@@ -75,10 +102,13 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
       // Fetch configuration
       const configResponse = await api.getConfig();
       // Backward compatibility: normalize legacy 'custom_screen' (with elements) to 'noboard_screen'
-      const normalizedScreens = configResponse.config.screens.map(s => ({
-        ...s,
-        type: (s.type === ('custom_screen' as any) && s.elements) ? 'noboard_screen' as ScreenConfig['type'] : s.type,
-      }));
+      const normalizedScreens = configResponse.config.screens
+        .map(s => ({
+          ...s,
+          type: (s.type === ('custom_screen' as any) && s.elements) ? 'noboard_screen' as ScreenConfig['type'] : s.type,
+        }))
+        // Filter out hidden screens (dashboard show/hide feature)
+        .filter(s => !s.hidden);
       setScreens(normalizedScreens);
 
       setLoading(false);
@@ -103,6 +133,13 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
     }
   };
 
+  const handleBack = () => {
+    // Navigate to previous screen (only if not on first screen)
+    if (currentIndex > 0) {
+      setCurrentIndex((prev) => prev - 1);
+    }
+  };
+
   const handleSkipScreen = () => {
     // Move to next screen or complete
     if (currentIndex >= screens.length - 1) {
@@ -235,6 +272,7 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
         <CustomComponent
           analytics={analyticsRef.current!}
           onNext={() => handleNext()}
+          onBack={currentIndex > 0 ? handleBack : undefined}
           onSkip={onSkip ? handleSkipAll : undefined}
           data={collectedData}
           onDataUpdate={(newData) => setCollectedData(prev => ({ ...prev, ...newData }))}

package/src/components/ElementRenderer.tsx

@@ -216,11 +216,19 @@ const RenderNode: React.FC<RenderNodeProps> = ({ element, toggledIds, groupSelec
   const hasAction = !!element.action || (element.actions && element.actions.length > 0);
   const wrapWithAction = (content: React.ReactElement): React.ReactElement => {
     if (!hasAction) return content;
+
+    // Extract width/alignment styles that should apply to TouchableOpacity wrapper
+    // This ensures buttons with width: "100%" don't shrink to content
+    const wrapperStyle: any = {};
+    if (style.width) wrapperStyle.width = style.width;
+    if (style.alignSelf) wrapperStyle.alignSelf = style.alignSelf;
+
     return (
       <TouchableOpacity
         key={element.id}
         activeOpacity={0.7}
         onPress={() => onAction(element)}
+        style={wrapperStyle}
       >
         {content}
       </TouchableOpacity>
@@ -439,9 +447,17 @@ const RenderNode: React.FC<RenderNodeProps> = ({ element, toggledIds, groupSelec
       );
 
     case 'input':
+      // Only apply default border if borderWidth is not explicitly defined (including 0)
+      const inputStyle = style as TextStyle;
+      const defaultInputStyle: TextStyle = {};
+      if (element.style?.borderWidth === undefined && element.style?.borderColor === undefined) {
+        defaultInputStyle.borderWidth = 1;
+        defaultInputStyle.borderColor = '#E5E5E5';
+      }
+
       return (
         <TextInput
-          style={[style as TextStyle, { borderWidth: 1, borderColor: '#E5E5E5' }]}
+          style={[defaultInputStyle, inputStyle]}
           placeholder={element.props?.placeholder || 'Enter text...'}
           keyboardType={getKeyboardType(element.props?.type)}
           secureTextEntry={element.props?.type === 'password'}

package/src/types.ts

@@ -12,6 +12,8 @@ export interface ScreenConfig {
   elements?: ElementNode[];
   // For custom_screen type — name of the developer-registered component
   custom_component_name?: string;
+  // Dashboard visibility control — if true, screen is hidden from onboarding flow
+  hidden?: boolean;
 }
 
 // ─── Element Tree Types (matches dashboard primitives) ───
@@ -224,6 +226,7 @@ export interface CustomScreenProps {
     track: (event: string, properties?: Record<string, any>) => void;
   };
   onNext: () => void;
+  onBack?: () => void;
   onSkip?: () => void;
   preview?: boolean;
   data?: Record<string, any>;
@@ -232,7 +235,13 @@ export interface CustomScreenProps {
 
 // Main SDK props
 export interface OnboardingFlowProps {
-  apiKey: string;
+  // Option 1: Auto-detection with dual keys (recommended)
+  testKey?: string;        // nb_test_... key for development/testing
+  productionKey?: string;  // nb_live_... key for production
+
+  // Option 2: Legacy single key (backwards compatible)
+  apiKey?: string;
+
   onComplete: (data?: Record<string, any>) => void;
   onSkip?: () => void;
   baseUrl?: string;