# Onairos Package v0.2.143

A Flutter package for opening a custom overlay using deep links and passing data between applications. Now with enhanced OAuth connection functionality for various platforms.

## Features

- Open a custom overlay with a deep link.
- Pass request data and a return link to the overlay.
- Customizable button with the Onairos logo.
- OAuth connections to multiple platforms (YouTube, Instagram, Pinterest, Reddit).
- Bottom modal overlay design for all UI components.
- Native SDK integration when available (Google Sign-In for YouTube).
- Fallback to web OAuth flows for platforms without native SDKs.

## Getting Started

To use the Onairos package, include it in your `pubspec.yaml` file:

```yaml
dependencies:
  onairos: ^0.1.0
```

## 🚨 **CRITICAL: Required Setup for YouTube/Google Integration**

**Before using YouTube integration**, you MUST configure your own Google credentials. The package uses demo credentials that will not work in production.

**Quick Setup:**
1. Create Google Cloud project
2. Enable YouTube Data API v3  
3. Create OAuth 2.0 credentials for your bundle ID/package name
4. Download `GoogleService-Info.plist` (iOS) and `google-services.json` (Android)
5. Provide your client ID to the Onairos widget

**See [CONSUMING_APP_SETUP_GUIDE.md](CONSUMING_APP_SETUP_GUIDE.md) for detailed instructions.**

## iOS Integration

To handle onairos biometric key store access (necessary) and other functionality on iOS with the Onairos package, you need to add the following configuration to your `Info.plist` file:

1st configurations

```xml
<key>NSFaceIDUsageDescription</key>
<string>Authenticate to access secure storage</string>
<key>NSBiometryUsageDescription</key>
<string>This app requires access to your biometric information for authentication purposes.</string>
<key>keychain-access-groups</key>
<array>
  <string>$(AppIdentifierPrefix)com.example.yourappbundleid</string>
</array>
```

2nd 

```
Secure Enclave Access:

In your app's target settings, under the "Signing & Capabilities" tab, add the "Secure Enclave" capability.
```



Then add the following Deep Link Permissions
## Configuring Your App for Deep Links

### iOS Configuration
1. **Update Info.plist:**
   - To handle deep links, you must declare your URL schemes in your `Info.plist` under `CFBundleURLTypes`. Here's how you can add a custom URL scheme:
     ```xml
     <key>LSApplicationQueriesSchemes</key>
      <array>
        <string>onairos</string>
      </array>
     <key>CFBundleURLTypes</key>
     <array>
         <dict>
             <key>CFBundleURLSchemes</key>
             <array>
                 <string>your-custom-scheme</string>
             </array>
         </dict>
     </array>
     ```
   - This configuration allows iOS to direct URLs with `your-custom-scheme` to your app.

2. **Handle Incoming URLs:**
   - Implement the `application(_:open:options:)` method in your `AppDelegate`:
     ```swift
     func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
         return true
     }
     ```

### Android Configuration
1. **Update AndroidManifest.xml:**
   - Declare your URL schemes within an `<intent-filter>` in your `AndroidManifest.xml`:
     ```xml
     <activity android:name=".MainActivity">
         <intent-filter>
             <action android:name="android.intent.action.VIEW" />
             <category android:name="android.intent.category.DEFAULT" />
             <category android:name="android.intent.category.BROWSABLE" />
             <data android:scheme="your-custom-scheme" />
         </intent-filter>
     </activity>
     ```
   - This configuration directs URLs with `your-custom-scheme` to your app.

2. **Handle Intent in Activity:**
   - Manage the Intent in your `onCreate` or `onNewIntent` method:
     ```java
     @Override
     protected void onNewIntent(Intent intent) {
         super.onNewIntent(intent);
         // Process the intent to extract data
     }
     ```

## Testing Your Setup
- **iOS**: Use Xcode or Safari to test your URL scheme by typing it into the address bar.
- **Android**: Use ADB to test your URL scheme:
  ```bash
  adb shell am start -W -a android.intent.action.VIEW -d "your-custom-scheme://test" com.example.yourapp


Additionally make sure to have the following AppDelegate.swift file included in your project

```swift

import UIKit
import Flutter

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

```

## Usage

### Onairos Button Integration

# Adding the Onairos button integration 

Inputs:
 - requestData (Object): Request data to display to user, what user data you want access to
 - returnLink (String): The registered CFBundleURL of your app, so the onairos app can redirect back on first authorization
 - logoAssetPath (String): String path of the logo you want to display when requesting access

Here is a simple example of using the OnairosButton widget in your app:

```dart

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

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: Center(
          // Use the OnairosButton widget
          child: OnairosButton(
            requestData: {
              'type': 'Personality',
              'descriptions': 'Find out Your Anime Interests',
              'reward': "\$0.30 - Test Money",
            },
            returnLink: 'yourapp://returnlink',
            logoAssetPath: 'onairos_logo.png',
          ),
        ),
      ),
    );
  }
}

```

Replace 'yourapp://returnlink' with the actual return link for your application, and ensure the logoAssetPath points to a valid asset in your project.

## Customization
The OnairosButton widget allows for customization of the request data and return link. Make sure to provide a valid asset path to display the Onairos logo on the button.

## OAuth Integration

### Using the Universal Onboarding Component

The Universal Onboarding component provides a complete solution for connecting to multiple platforms:

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

// Inside your widget
void showOnboarding() {
  showModalBottomSheet(
    context: context,
    isScrollControlled: true,
    backgroundColor: Colors.transparent,
    builder: (context) => UniversalOnboarding(
      platforms: ['youtube', 'instagram', 'pinterest', 'reddit'],
      onComplete: (connectedPlatforms) {
        // Handle connected platforms
        print('Connected platforms: $connectedPlatforms');
      },
    ),
  );
}
```

### Direct OAuth Service Usage

For more control, you can use the OAuthService directly:

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

// Inside your widget
final oauthService = OAuthService();

Future<void> connectToYouTube() async {
  final connected = await oauthService.connectYouTube(context);
  if (connected) {
    // Successfully connected
  } else {
    // Connection failed
  }
}
```

For more detailed information on OAuth integration, please refer to the [OAuth Integration Guide](docs/oauth_integration_guide.md).

## Contributing
Feel free to contribute to the Onairos package. If you have suggestions or find bugs, please open an issue or create a pull request.
