URL Flow SDK POC

A reusable Flutter SDK that opens URLs with timed redirects and auto-close functionality. Perfect for payment flows, OAuth callbacks, and promotional pages.

Features

• 🌐 Open a URL in an embedded WebView
• ⏱️ Wait for a configurable duration
• 🔄 Automatically redirect to a second URL
• 🚪 Auto-close after another delay
• 📊 Return detailed session results
• 🔒 Jailbreak/Root detection (v1.1.0)
• 🌍 URL domain validation (v1.2.0)
• 🧹 Proper cleanup of timers and resources

Installation

Add the SDK to your pubspec.yaml:

dependencies:
  url_flow_sdk_poc: ^1.2.0

Then run:

flutter pub get

Android Configuration

For Android, ensure your app has a minimum SDK of 21 or higher in android/app/build.gradle.kts:

android {
    defaultConfig {
        minSdk = 21
    }
}

Usage

Basic Usage

import 'package:url_flow_sdk_poc/url_flow_sdk_poc.dart';

// Create a controller
final controller = WebFlowController();

// Start a session
final result = await controller.startSession(
  context: context,
  config: WebFlowConfig(
    initialUrl: 'https://example.com/start',
    redirectUrl: 'https://example.com/complete',
    initialDelay: Duration(seconds: 5),
    redirectDelay: Duration(seconds: 3),
  ),
);

// Handle the result
if (result.isSuccess) {
  print('✅ Session completed successfully!');
  print('Duration: ${result.sessionDuration}');
} else if (result.isCancelled) {
  print('❌ User cancelled the session');
} else if (result.isDeviceForbidden) {
  print('🔒 Device failed security checks: ${result.errorMessage}');
} else {
  print('⚠️ Error: ${result.errorMessage}');
}

Quick Start (Convenience Method)

import 'package:url_flow_sdk_poc/url_flow_sdk_poc.dart';

// Use the global instance with quick start
final result = await webFlow.quickStart(
  context: context,
  initialUrl: 'https://example.com/start',
  redirectUrl: 'https://example.com/complete',
  title: 'Verification',
);

Full Configuration Options

WebFlowConfig(
  // Required
  initialUrl: 'https://example.com/start',
  redirectUrl: 'https://example.com/complete',
  
  // Timing (optional)
  initialDelay: Duration(seconds: 5),  // Default: 5 seconds
  redirectDelay: Duration(seconds: 3), // Default: 3 seconds
  
  // UI Options (optional)
  title: 'My Web Flow',                // AppBar title
  showLoadingIndicator: true,          // Show progress bar
  showNavigationControls: false,       // Show back/forward buttons
  enableJavaScript: true,              // Enable JS in WebView
  
  // Security (optional) - v1.1.0+
  enableSecurityCheck: true,           // Enable jailbreak/root detection
  securityOptions: SecurityCheckOptions.strict(),
  
  // URL Validation (optional) - v1.2.0+
  urlDomainConfig: UrlDomainConfig.production('myapp.com'),
  onNavigationBlocked: (url, reason) => print('Blocked: $url'),
)

🔒 Security Features

Jailbreak/Root Detection (v1.1.0)

final result = await controller.startSession(
  context: context,
  config: WebFlowConfig(
    initialUrl: 'https://payment.example.com/checkout',
    redirectUrl: 'https://payment.example.com/success',
    enableSecurityCheck: true,
    securityOptions: SecurityCheckOptions.strict(),
  ),
);

if (result.isDeviceForbidden) {
  // Device is rooted/jailbroken - block the transaction
  showDialog(
    context: context,
    builder: (_) => AlertDialog(
      title: Text('Security Alert'),
      content: Text('This app cannot run on compromised devices.'),
    ),
  );
}

URL Domain Validation (v1.2.0)

final config = WebFlowConfig(
  initialUrl: 'https://payment.myapp.com/checkout',
  redirectUrl: 'https://payment.myapp.com/success',
  
  // Only allow your domain and subdomains
  urlDomainConfig: UrlDomainConfig.production('myapp.com'),
  
  onNavigationBlocked: (url, reason) {
    print('Blocked navigation to $url: $reason');
  },
);

Domain Config Presets

Preset	Description
UrlDomainConfig()	Allow all domains
UrlDomainConfig.strict(['domain.com'])	Only specified domains, HTTPS required
UrlDomainConfig.blocklist(['evil.com'])	Block specific domains
UrlDomainConfig.production('myapp.com')	Domain + subdomains, HTTPS required
UrlDomainConfig.development()	Allow all + localhost

Result Handling

// Status enum
result.status; // WebFlowStatus.success, .cancelled, .error, or .deviceForbidden

// Convenience getters
result.isSuccess;         // true if completed successfully
result.isCancelled;       // true if user closed manually
result.isError;           // true if an error occurred
result.isDeviceForbidden; // true if device failed security checks

// Session info
result.lastUrl;         // The URL when session ended
result.sessionDuration; // How long the session was active
result.errorMessage;    // Error details (if status is error or deviceForbidden)

How It Works

1. Security Check (if enabled): Verify device is not rooted/jailbroken
2. URL Validation (if configured): Validate initial and redirect URLs
3. Start Session: Open WebView with initial URL
4. Wait: After page loads, wait for initialDelay duration
5. Redirect: Navigate to redirectUrl
6. Wait Again: Wait for redirectDelay duration
7. Auto-Close: Screen closes and returns a success result

Example Use Cases

• Payment Gateway: Secure checkout flows with jailbreak detection
• OAuth Flows: Handle authentication redirects
• Ad Verification: Show an ad page, then redirect to content
• Promotional Pages: Display a promo, then redirect to app

License

MIT License - See LICENSE file for details