# Onairos Flutter SDK - Latest Implementation Guide

## 🚀 Quick Start

### 1. Add Dependency
```yaml
# pubspec.yaml
dependencies:
  onairos: ^1.10.1+2
```

### 2. Basic Integration
```dart
import 'package:onairos/onairos.dart';

// Simple Onairos button
Onairos(
  AppName: "Your App Name",
  buttonForm: "connect",
  onResolved: (apiUrl, token, userData) {
    // Handle successful connection
    print('Connected with token: $token');
    print('User data: $userData');
  },
)
```

## 📱 Working Implementation Patterns

### Pattern 1: Simple Connect Button (Recommended)
```dart
Onairos(
  AppName: "Your App Name",
  buttonForm: "connect",
  customButtonText: "Connect with Onairos",
  buttonWidth: double.infinity,
  buttonHeight: 56,
  testMode: true,
  testModeType: 'universal_onboarding',
  onResolved: (apiUrl, token, userData) {
    // Navigate to next screen
    Navigator.pushReplacementNamed(context, '/dashboard');
  },
)
```

### Pattern 2: Login Integration
```dart
Onairos(
  AppName: "Your App Name",
  buttonForm: "login",
  customButtonText: "Sign in with Onairos",
  testMode: true,
  testModeType: 'universal_onboarding',
  preferredPlatform: 'YouTube,Google', // Prioritize specific platforms
  onResolved: (apiUrl, token, userData) {
    // Handle login success
    Navigator.pushReplacementNamed(context, '/dashboard');
  },
)
```

### Pattern 3: Data Request with Custom Types
```dart
Onairos(
  requestData: {
    'Small': {
      'type': 'Personality',
      'descriptions': 'Connect with Onairos to personalize your experience',
      'reward': 'Enhanced recommendations',
    },
    'Medium': {
      'type': 'Personality',
      'descriptions': 'Get better matches with Onairos',
      'reward': 'AI-powered compatibility',
    },
    'Large': {
      'type': 'Personality',
      'descriptions': 'Unlock full Onairos intelligence',
      'reward': 'Complete personalization',
    },
  },
  returnLink: 'your-app-name',
  onResolved: (apiUrl, token, userData) {
    // Handle data collection success
    Navigator.pushReplacementNamed(context, '/dashboard');
  },
  AppName: "Your App Name",
  buttonType: "pill",
  buttonForm: "connect",
)
```

### Pattern 4: Modal Flow Integration
```dart
import 'package:onairos/screens/npm_modal_flow.dart';

void _showOnairosFlow(BuildContext context) {
  showDialog(
    context: context,
    barrierDismissible: false,
    builder: (context) => Dialog.fullscreen(
      child: NpmModalFlow(
        visible: true,
        onClose: () => Navigator.pop(context),
        appName: 'Your App Name',
        onResolved: (apiUrl, token, userData) {
          Navigator.pop(context);
          
          // Navigate after modal closes
          Future.delayed(const Duration(milliseconds: 200), () {
            if (context.mounted) {
              Navigator.pushReplacementNamed(
                context,
                '/dashboard',
                arguments: {'isOnairosLogin': true}
              );
            }
          });
        },
      ),
    ),
  );
}
```

## 🎨 Styling Options

### Button Customization
```dart
Onairos(
  AppName: "Your App Name",
  buttonForm: "connect",
  customButtonText: "Connect with Onairos",
  buttonWidth: double.infinity,
  buttonHeight: 56,
  buttonType: "pill", // "pill" or "rectangular"
  color: Colors.purple.shade700, // Custom button color
  darkMode: true, // For dark themes
)
```

### Theme Integration
```dart
Onairos(
  AppName: "Your App Name",
  buttonForm: "connect",
  darkMode: true, // Matches dark theme
  color: Theme.of(context).primaryColor,
  onResolved: (apiUrl, token, userData) {
    // Handle success
  },
)
```

## 🔧 Advanced Configuration

### Platform Preferences
```dart
Onairos(
  AppName: "Your App Name",
  preferredPlatform: 'YouTube,Google,Instagram', // Comma-separated list
  testMode: true,
  testModeType: 'universal_onboarding',
  onResolved: (apiUrl, token, userData) {
    // Handle success
  },
)
```

### Custom Data Types
```dart
Onairos(
  requestData: {
    'anime_preferences': {
      'name': 'Anime Preferences',
      'description': 'Your favorite anime genres and viewing habits',
      'reward': 'Personalized anime recommendations',
    },
    'viewing_history': {
      'name': 'Viewing History',
      'description': 'Your anime watching patterns and preferences',
      'reward': 'Better content discovery and recommendations',
    },
  },
  returnLink: 'your-app-name',
  onResolved: (apiUrl, token, userData) {
    // Handle success
  },
)
```

## 🚨 Common Issues & Solutions

### Navigation Issues
**Problem**: App reverts to previous screen after Onairos completion
**Solution**: Use proper navigation timing
```dart
onResolved: (apiUrl, token, userData) {
  // Close modal first
  Navigator.pop(context);
  
  // Then navigate after delay
  Future.delayed(const Duration(milliseconds: 200), () {
    if (context.mounted) {
      Navigator.pushReplacementNamed(context, '/dashboard');
    }
  });
}
```

### Context Safety
**Problem**: Navigation errors on disposed widgets
**Solution**: Always check context.mounted
```dart
onResolved: (apiUrl, token, userData) {
  Future.delayed(const Duration(milliseconds: 100), () {
    if (context.mounted) {
      Navigator.pushReplacementNamed(context, '/dashboard');
    }
  });
}
```

### Modal Flow Issues
**Problem**: Modal doesn't close properly
**Solution**: Use proper modal closing sequence
```dart
onResolved: (apiUrl, token, userData) {
  Navigator.pop(context); // Close modal first
  Future.delayed(const Duration(milliseconds: 200), () {
    if (context.mounted) {
      Navigator.pushReplacementNamed(context, '/dashboard');
    }
  });
}
```

## 📋 Complete Example

```dart
import 'package:flutter/material.dart';
import 'package:onairos/onairos.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: Center(
          child: Onairos(
            AppName: "My App",
            buttonForm: "connect",
            customButtonText: "Connect with Onairos",
            buttonWidth: double.infinity,
            buttonHeight: 56,
            testMode: true,
            testModeType: 'universal_onboarding',
            preferredPlatform: 'YouTube,Google',
            onResolved: (apiUrl, token, userData) {
              // Handle successful connection
              Navigator.pushReplacementNamed(context, '/dashboard');
            },
          ),
        ),
      ),
    );
  }
}
```

## 🔗 Working Demo Apps

The following demo apps show working implementations:

- **Cosmos** (`/cosmos/welcome`) - Anime discovery app
- **Huxe** (`/huxe/setup`) - Audio intelligence app  
- **Oboe** (`/oboe/login`) - Personal tutor app
- **Boo** (`/boo/welcome`) - Dating platform
- **StarkFit** (`/StarkfitLogin`) - Fitness tracking

## 📚 API Reference

### Onairos Widget Parameters

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `AppName` | String | Your app name | Required |
| `buttonForm` | String | "connect" or "login" | "connect" |
| `customButtonText` | String | Custom button text | Auto-generated |
| `buttonWidth` | double | Button width | 200 |
| `buttonHeight` | double | Button height | 48 |
| `buttonType` | String | "pill" or "rectangular" | "rectangular" |
| `color` | Color | Button color | Theme primary |
| `darkMode` | bool | Dark theme mode | false |
| `testMode` | bool | Enable test mode | false |
| `testModeType` | String | Test flow type | "standard" |
| `preferredPlatform` | String | Platform preferences | null |
| `requestData` | Map | Custom data types | null |
| `returnLink` | String | Return link identifier | null |
| `onResolved` | Function | Success callback | Required |

### Callback Function
```dart
void onResolved(String apiUrl, String token, Map<String, dynamic> userData) {
  // apiUrl: API endpoint URL
  // token: User authentication token
  // userData: Collected user data
}
```

## 🎯 Best Practices

1. **Always use context.mounted checks** for navigation
2. **Add delays** for smooth modal transitions
3. **Use testMode: true** during development
4. **Set preferredPlatform** for better user experience
5. **Handle errors gracefully** with try-catch blocks
6. **Use pushReplacementNamed** for main navigation
7. **Close modals before navigation** to prevent conflicts

## 🔄 Version History

- **v1.10.1+2**: Latest stable version with navigation fixes
- **v1.10.0+1**: Previous version with modal flow improvements
- **v1.9.x**: Core functionality and platform integrations

## 📞 Support

For issues or questions:
- Check the working demo apps for reference implementations
- Review the integration guide for detailed setup
- Test with `testMode: true` for development
