simplici_auth 1.3.7

A Flutter package for integrating SimpliciAuth with Google OAuth in Flutter applications. Provides webview-based authentication with customizable configuration and comprehensive OAuth handling.

SimpliciAuth Flutter

A Flutter package for integrating SimpliciAuth with Google OAuth in Flutter applications. This package provides webview-based authentication with customizable configuration and comprehensive OAuth handling.

Features

• 🔐 Multi-Platform OAuth Integration: Complete OAuth 2.0 flow with Google, Apple, Facebook, and Microsoft
• 🌐 WebView Authentication: Secure webview-based authentication with custom styling
• 📱 Cross-Platform Support: Works on iOS, Android, Web, macOS, Linux, and Windows
• 🎨 Customizable Configuration: Fully configurable with props for all authentication parameters
• 🔄 Token Management: Automatic token exchange and refresh handling
• 📊 User Data Retrieval: Complete user profile information retrieval
• ⚡ Hook System Integration: Built-in integration with window.handleHooks for custom flows
• 🛡️ Comprehensive Error Handling: Detailed error handling and optional debug logging
• 📋 Callback Support: Multiple callback functions for different authentication events

Installation

Add this to your app's pubspec.yaml file:

dependencies:
  simplici_auth_flutter:
    path: ./simplici_auth_flutter  # Local path to package

Then run:

flutter pub get

Usage

Basic Usage

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:simplici_auth_flutter/simplici_auth_flutter.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Hide system UI for fullscreen experience
  SystemChrome.setEnabledSystemUIMode(SystemUiMode.immersiveSticky);
  
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(
        scaffoldBackgroundColor: Colors.transparent,
      ),
      home: SimpliciAuthWebView(
        config: SimpliciAuthConfig(
          instanceId: "your-instance-id-here",
          environment: "beta", // or "production"
          debugMode: true,
          onAuthComplete: (result) {
            print('Authentication successful: $result');
          },
          onAuthError: (error) {
            print('Authentication failed: $error');
          },
        ),
      ),
    );
  }
}

Advanced Configuration

class AuthScreen extends StatefulWidget {
  @override
  _AuthScreenState createState() => _AuthScreenState();
}

class _AuthScreenState extends State<AuthScreen> {
  void _handleAuthComplete(Map<String, dynamic> result) {
    // Handle successful authentication
    final userEmail = result['email'];
    final provider = result['provider'];
    final accessToken = result['access_token'];
    
    print('User authenticated: $userEmail via $provider');
    
    // Navigate to home screen or update UI
    Navigator.pushReplacementNamed(context, '/home');
  }

  void _handleAuthError(String error) {
    // Handle authentication error
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text('Authentication failed: $error'),
        backgroundColor: Colors.red,
      ),
    );
  }

  void _handleStepChanged(Map<String, dynamic> event) {
    // Handle step changes in authentication flow
    print('Authentication step changed: $event');
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Authentication')),
      body: SimpliciAuthWebView(
        config: SimpliciAuthConfig(
          instanceId: "your-instance-id-here",
          environment: "production",
          platform: "ios", // or "android", "web"
          isCombinedInput: true,
          autoNavigate: true,
          debugMode: false,
          baseUrl: "https://auth.yourdomain.com",
          userAgent: "YourApp/1.0.0",
          onAuthComplete: _handleAuthComplete,
          onAuthError: _handleAuthError,
          onStepChanged: _handleStepChanged,
          customCSS: """
            .fullscreen-container {
              background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
            }
          """,
          additionalAttributes: {
            'theme': 'dark',
            'language': 'en',
          },
        ),
      ),
    );
  }
}

Configuration Options

SimpliciAuthConfig

Parameter	Type	Default	Description
instanceId	String	required	Your SimpliciAuth instance ID
environment	String	"beta"	Environment (beta, production, etc.)
isCombinedInput	bool	true	Whether to use combined input mode
autoNavigate	bool	true	Whether to enable auto navigation
platform	String	"ios"	Platform (ios, android, web)
baseUrl	String	"https://auth.beta.satschel.com"	Base URL for SimpliciAuth service
jsPath	String	"/static/js/main.js"	Path to JavaScript file
userAgent	String?	null	Custom user agent (uses platform default if null)
debugMode	bool	false	Enable debug logging
customCSS	String?	null	Custom CSS styles
additionalAttributes	Map<String, String>?	null	Additional attributes for web component
onAuthComplete	Function?	null	Callback for successful authentication
onAuthError	Function?	null	Callback for authentication errors
onStepChanged	Function?	null	Callback for authentication step changes

Callback Functions

onAuthComplete

Called when authentication is successful. Receives a Map<String, dynamic> with:

• email: User's email address
• provider: Authentication provider (google, apple, facebook, microsoft)
• access_token: OAuth access token
• refresh_token: OAuth refresh token (if available)
• code: Authorization code
• expires_in: Token expiration time in seconds
• user_info: Complete user profile information
• Additional provider-specific data

onAuthError

Called when authentication fails. Receives a String with the error message.

onStepChanged

Called when the authentication flow changes steps. Receives a Map<String, dynamic> with step information.

Platform-Specific Setup

iOS

Add the following to your ios/Runner/Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSExceptionDomains</key>
  <dict>
    <key>auth.beta.satschel.com</key>
    <dict>
      <key>NSExceptionAllowsInsecureHTTPLoads</key>
      <true/>
      <key>NSIncludesSubdomains</key>
      <true/>
    </dict>
  </dict>
</dict>

Android

Add internet permission to your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

Authentication Flow

1. Instance Details: WebView receives SimpliciAuth instance configuration
2. OAuth Configuration: Google OAuth settings are configured automatically
3. User Authentication: User authenticates via selected provider
4. Token Exchange: Authorization code is exchanged for access token
5. Hook Integration: window.handleHooks is called with authentication data
6. User Data Retrieval: Complete user profile is fetched
7. Callback Execution: Your callback functions are called with results

Response Format

The onAuthComplete callback receives data in this format:

{
  "provider": "google",
  "access_token": "ya29.a0...",
  "refresh_token": "1//04...",
  "code": "4/0AfJohX...",
  "expires_in": 3599,
  "email": "[e-mail]",
  "userId": "user-id",
  "firstName": "John",
  "lastName": "Doe",
  "user_info": {
    "id": "123456789",
    "email": "[e-mail]",
    "verified_email": true,
    "name": "John Doe",
    "given_name": "John",
    "family_name": "Doe",
    "picture": "https://..."
  },
  "hook_result": {
    "statusCode": 200,
    "message": "ok",
    "data": { ... }
  }
}

Examples

Check out the example applications:

• Main Demo: lib/main.dart - Basic authentication flow
• Advanced Example: simplici_auth_flutter/example/ - Full-featured implementation

Requirements

• Flutter SDK: >=1.17.0
• Dart SDK: ^3.8.1

Dependencies

The package uses these dependencies:

• webview_flutter: ^4.2.2 - Cross-platform webview support
• flutter_inappwebview: ^6.0.0 - Advanced webview features
• http: ^1.1.0 - HTTP requests for OAuth token exchange

Platform Support

Platform	Support
Android	✅
iOS	✅
Web	✅
macOS	✅
Linux	✅
Windows	✅

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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

Support

For support, please contact the SimpliciAuth team or create an issue in this repository.