Remit2Any Auth Flutter SDK #

A comprehensive Flutter package for seamless AWS Cognito authentication via optimized WebViews for Remit2Any. This package provides enhanced WebView components with advanced keyboard handling, permission management, and secure token storage.

✨ Features #

🔐 Authentication & Security #

WebView-based authentication with Remit2Any Cognito integration
Secure token storage using flutter_secure_storage
Automatic token refresh with background refresh capabilities
User profile management with Cognito user data fetching
Session management with automatic logout detection

📱 Enhanced WebView Experience #

Advanced keyboard handling for iOS and Android
Smart input field scrolling to prevent keyboard overlap
Automatic permission requests for camera and microphone (KYC processes)
WhatsApp URL handling with external browser redirect
Multi-domain support with intelligent URL routing
File download capabilities with native file manager integration

🛡️ Robust Permission Management #

Dynamic permission handling for US KYC and KYC documents
Platform-specific optimizations for iOS and Android
Secure domain validation for WebView navigation
Cross-platform compatibility with consistent behavior

🌐 Flexible Environment Management #

Development and production environment support
Configurable URLs and settings per environment
Custom user agent management for WebView identification

🚀 Installation #

Add to your pubspec.yaml:

dependencies:
  remit2any_auth: ^0.1.1

Run:

flutter pub get

📋 Required Permissions #

Android

Add to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

iOS

Add to ios/Runner/Info.plist:

<key>NSCameraUsageDescription</key>
<string>This app needs camera access to capture documents for identity verification and KYC compliance.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access for identity verification processes and KYC compliance.</string>
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

⚙️ Configuration #

Environment Setup #

Configure your environment in your app initialization:

import 'package:remit2any_auth/remit2any_auth.dart';

void main() {
  // Set environment (dev or prod)
  Remit2AnyEnvironmentConfig.setEnvironment(Environment.prod);
  
  // Optional: Set custom user agent suffix
  Remit2AnyEnvironmentConfig.setUserAgentSuffix('embeddableuseragent');
  
  runApp(MyApp());
}

Supported Environments #

Development: Environment.dev → https://dev.remit2any.com
Production: Environment.prod → https://remit2any.com

📖 Usage #

Basic Authentication Flow #

import 'package:remit2any_auth/remit2any_auth.dart';

class AuthService {
  final Remit2AnyAuth _auth = Remit2AnyAuth();

  // Sign in with optional email pre-fill
  Future<Map<String, dynamic>?> signIn(BuildContext context, {String? email}) async {
    final tokens = await _auth.signIn(context, email: email);
    
    if (tokens != null) {
      // Authentication successful
      print('Access Token: ${tokens['accessToken']}');
      print('User Email: ${tokens['email']}');
      print('User ID: ${tokens['userId']}');
      return tokens;
    }
    return null;
  }

  // Get current user information
  Future<UserInfo?> getCurrentUser() async {
    return await _auth.getUser();
  }

  // Sign out (clears tokens and Cognito session)
  Future<void> signOut(BuildContext context) async {
    await _auth.signOut(context);
  }
}

Advanced WebView Navigation #

class WebViewService {
  final Remit2AnyAuth _auth = Remit2AnyAuth();

  // Open US KYC with automatic camera/microphone permissions
  Future<void> openKycProcess(BuildContext context) async {
    final result = await _auth.openUsKyc(context);
    
    if (result != null && result['loggedOut'] == true) {
      // Handle logout scenario
      _handleLogout(context);
    }
  }

  // Open transfer page with custom amount
  Future<void> openTransfer(BuildContext context, double amount) async {
    final result = await _auth.openTransfer(context, usdAmount: amount);
    _handleWebViewResult(context, result);
  }

  // Open wallet deposit
  Future<void> openWallet(BuildContext context) async {
    final result = await _auth.openWalletDeposit(context);
    _handleWebViewResult(context, result);
  }

  // Open transactions history
  Future<void> openTransactions(BuildContext context) async {
    final result = await _auth.openTransactions(context);
    _handleWebViewResult(context, result);
  }

  void _handleWebViewResult(BuildContext context, Map<String, dynamic>? result) {
    if (result != null && result['loggedOut'] == true) {
      _handleLogout(context);
    }
  }

  void _handleLogout(BuildContext context) {
     final tokens = await _auth.signIn(context, email: email);
  }
}

Token Management #

class TokenManager {
  final Remit2AnyAuth _auth = Remit2AnyAuth();

  // Get stored user data
  Future<Map<String, String?>> getStoredUserData() async {
    final email = await _auth.getStoredEmail();
    final userId = await _auth.getStoredUserId();
    
    return {
      'email': email,
      'userId': userId,
    };
  }

  // Check KYC completion status
  Future<bool> checkKycStatus() async {
    return await _auth.isUsKycCompleted();
  }
}

Custom WebView Integration #

For advanced use cases, you can use the WebView components directly:

🎯 Key Features Explained #

Enhanced Keyboard Handling #

The package includes advanced keyboard handling that automatically:

✅ Prevents input fields from being hidden behind the keyboard on iOS
✅ Maintains Android's existing smooth keyboard behavior
✅ Automatically scrolls focused input fields into view
✅ Handles viewport adjustments for optimal user experience

Intelligent Permission Management #

Permissions are requested dynamically based on URL patterns:

🎥 Camera & Microphone: Automatically requested for URLs containing uskyc or kyc-documents
🔒 Secure Domains: Only trusted Remit2Any domains are allowed
🌐 External URLs: WhatsApp links and other external URLs open in system browser

Smart WebView Navigation #

📱 Platform Optimization: Different behaviors optimized for iOS and Android
🔄 User Agent Management: Dynamic user agent switching for different services (Google OAuth, etc.)
📁 File Downloads: Native file download handling with system integration
🔐 Security: SSL certificate validation with custom handling

🛠️ Advanced Configuration #

Environment Variables #

// Check current environment
if (Remit2AnyEnvironmentConfig.isDev) {
  print('Development mode');
} else {
  print('Production mode');
}

// Get environment-specific URLs
print('Auth URL: ${Remit2AnyEnvironmentConfig.authUrl}');
print('Base URL: ${Remit2AnyEnvironmentConfig.baseUrl}');
print('User Agent Suffix: ${Remit2AnyEnvironmentConfig.userAgentSuffix}');


## 🔧 Dependencies

This package depends on:
- **flutter_inappwebview**: ^6.0.0 - Advanced WebView functionality
- **flutter_secure_storage**: ^9.0.0 - Secure token storage
- **http**: ^1.0.0 - HTTP requests for API calls
- **permission_handler**: ^11.0.0 - Runtime permission management
- **url_launcher**: ^6.1.4 - External URL handling
- **path_provider**: ^2.1.1 - File system access for downloads

## 🐛 Troubleshooting

### Common Issues

📱 Platform Support #

Platform	WebView	Auth	Permissions	File Download	Keyboard
Android	✅	✅	✅	✅	✅
iOS	✅	✅	✅	✅	✅
Web	⚠️	⚠️	❌	❌	❌
macOS	⚠️	⚠️	⚠️	⚠️	⚠️
Windows	⚠️	⚠️	⚠️	⚠️	⚠️

✅ Fully Supported | ⚠️ Limited Support | ❌ Not Supported

📚 API Reference #

Core Classes #

`Remit2AnyAuth`

Main authentication service class.

Methods:

signIn(BuildContext context, {String? email}) → Future<Map<String, dynamic>?>
signOut(BuildContext context) → Future<void>
getUser() → Future<UserInfo?>
openUsKyc(BuildContext context) → Future<Map<String, dynamic>?>
openTransfer(BuildContext context, {double? usdAmount}) → Future<Map<String, dynamic>?>
openWalletDeposit(BuildContext context) → Future<Map<String, dynamic>?>
openTransactions(BuildContext context) → Future<Map<String, dynamic>?>
isUsKycCompleted() → Future<bool>
getStoredEmail() → Future<String?>
getStoredUserId() → Future<String?>

`Remit2AnyEnvironmentConfig`

Environment configuration management.

Methods:

setEnvironment(Environment environment) → void
setUserAgentSuffix(String suffix) → void

Properties:

environment → Environment
authUrl → String
baseUrl → String
userAgentSuffix → String
isDev → bool

🔄 Migration Guide #

From v0.1.0 to v0.1.1 #

Enhanced keyboard handling for iOS
Improved permission management
Added WhatsApp URL handling
Enhanced WebView components

No breaking changes - update your pubspec.yaml version and run flutter pub get.

Development Setup #

git clone https://github.com/your-repo/remit2any_auth.git
cd remit2any_auth
flutter pub get
cd example
flutter pub get
flutter run

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ by the Remit2Any Team

remit2any_auth 0.1.2 remit2any_auth: ^0.1.2 copied to clipboard

Metadata