AeroSync Flutter SDK

A Flutter SDK that provides secure bank account linking for iOS, Android, and Flutter Web. Integrate AeroSync's bank connection widget into your Flutter app with ease, allowing users to securely connect their bank accounts through fast, tokenized connections.

Features

  • iOS & Android: Native WebView with full OAuth deeplink support
  • Flutter Web — System Browser mode: Widget opens in a centered popup window; OAuth flows inside the popup also open as proper popup windows (no cross-origin restrictions)
  • Flutter Web — Host mode: Widget renders inline as an iframe embed
  • MFA Support: Multi-factor authentication handling
  • Customizable: Theming and styling options

Requirements

  • Flutter 3.44+
  • Dart 3.3+
  • iOS 11.0+ / Android API level 21+

Installation

1. Add Dependency

dependencies:
  aerosync_flutter_sdk: ^2.0.0-rc.4

2. Install Dependencies

flutter pub get

3. Import the Library

import 'package:aerosync_flutter_sdk/aerosync_flutter_sdk.dart';

Mobile Integration (iOS & Android)

1. Configure Deep Linking

OAuth authentication redirects require a URL scheme registered on each platform.

Android — add an intent-filter inside your <activity> in android/app/src/main/AndroidManifest.xml:

<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="yourapp" android:host="connect" />
</intent-filter>

iOS — add the URL scheme to ios/Runner/Info.plist:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>yourapp</string>
        </array>
    </dict>
</array>

2. Add the Navigator Observer

Add AeroSyncNavigatorObserver to your MaterialApp. Required for iOS OAuth return to work correctly — without it, returning from the external browser pushes a spurious route that hides the widget.

const _deeplink = 'yourapp://connect';

MaterialApp(
  navigatorObservers: [AeroSyncNavigatorObserver(deeplink: _deeplink)],
  home: const HomePage(),
)

3. Launch the Widget

Show AeroSyncWidget via Navigator.push. The SDK auto-dismisses when onSuccess or onClose fires — do not call Navigator.pop inside these callbacks.

Navigator.of(context).push(MaterialPageRoute(
  builder: (context) => Scaffold(
    appBar: AppBar(title: const Text('Link Your Bank')),
    body: AeroSyncWidget(
      token: 'your-token-here',
      environment: 'sandbox',         // 'sandbox' or 'production'
      deeplink: 'yourapp://connect',
      aeroPassUserUuid: 'user-uuid-123',
      configurationId: 'your-config-id', // Optional
      theme: 'light',                 // 'light' or 'dark'
      style: {'bgColor': '#FFFFFF'},  // Optional
      onSuccess: (data) {
        // Bank linking completed — data contains account details.
        // Do NOT call Navigator.pop — the SDK handles dismissal.
      },
      onClose: (data) {
        // User closed the widget.
        // Do NOT call Navigator.pop — the SDK handles dismissal.
      },
      onEvent: (data) {},
      onError: (data) {},
      onLoad: (data) {},
    ),
  ),
));

MFA Flow

AeroSyncWidget(
  token: 'your-token-here',
  environment: 'sandbox',
  deeplink: 'yourapp://connect',
  aeroPassUserUuid: 'user-uuid-123',
  handleMFA: true,
  jobId: 'your-job-id',
  connectionId: 'your-connection-id',
  onSuccess: (data) {},
  onClose: (data) {},
  onEvent: (data) {},
  onError: (data) {},
  onLoad: (data) {},
)

Flutter Web Integration

On Flutter Web the deeplink parameter is automatically omitted from the widget URL — it would override the browser's return URL and break OAuth redirects back to your web app. Pass any value (or an empty string); it is ignored at runtime.

Two launch modes are available via the widgetLaunchType parameter.

System Browser mode (recommended — widgetLaunchType: 'systemBrowser')

The widget opens in a centered popup window launched from a user gesture. Because the popup runs in a top-level browsing context, OAuth bank redirects also open as proper popup windows (not tabs). This avoids Chrome's cross-origin iframe restriction.

The SDK shows a "Link Your Bank" button in your app; tapping it opens the popup. While the popup is open a spinner is shown. The popup closes automatically when the flow completes.

Navigator.of(context).push(MaterialPageRoute(
  builder: (context) => Scaffold(
    appBar: AppBar(title: const Text('Link Your Bank')),
    body: AeroSyncWidget(
      token: 'your-token-here',
      environment: 'sandbox',
      deeplink: '',                        // ignored on web
      aeroPassUserUuid: 'user-uuid-123',
      widgetLaunchType: 'systemBrowser',   // opens as popup window
      onSuccess: (data) {
        // Do NOT call Navigator.pop — the SDK handles dismissal.
      },
      onClose: (data) {},
      onEvent: (data) {},
      onError: (data) {},
      onLoad: (data) {},
    ),
  ),
));

Popup blocked? Browsers require a user gesture to open popups. Make sure the widget is launched from a button tap (not programmatically on page load). If the popup is still blocked, instruct users to allow popups for your domain.

Host mode (widgetLaunchType: 'host')

The widget renders inline as an <iframe> embed directly in your Flutter Web page. Use this when you want the bank link UI as part of the page layout.

Note: Some banks use OAuth flows that Chrome opens as a new tab instead of a popup window when triggered from a cross-origin iframe. The systemBrowser mode avoids this limitation entirely.

Navigator.of(context).push(MaterialPageRoute(
  builder: (context) => Scaffold(
    appBar: AppBar(title: const Text('Link Your Bank')),
    body: AeroSyncWidget(
      token: 'your-token-here',
      environment: 'sandbox',
      deeplink: '',                 // ignored on web
      aeroPassUserUuid: 'user-uuid-123',
      widgetLaunchType: 'host',     // inline iframe embed
      onSuccess: (data) {
        // Do NOT call Navigator.pop — the SDK handles dismissal.
      },
      onClose: (data) {},
      onEvent: (data) {},
      onError: (data) {},
      onLoad: (data) {},
    ),
  ),
));

API Reference

To generate a token, see the AeroSync integration guide.

AeroSyncWidget Parameters

Parameter Type Required Default Description
token String Yes — Authentication token for the session
environment String Yes — "sandbox" or "production"
deeplink String Yes — Deep link URL for OAuth redirects (mobile only; ignored on web)
aeroPassUserUuid String Yes — AeroPass user UUID
widgetLaunchType String No 'systemBrowser' Web only: 'systemBrowser' (popup) or 'host' (iframe)
configurationId String? No — Configuration ID for customization
theme String No 'light' UI theme: "light" or "dark"
style Map No {} Custom styling — supports bgColor (hex string)
handleMFA bool? No — Enable MFA flow handling
jobId String? No — Job ID — required when handleMFA is true
connectionId String? No — Connection ID — required when handleMFA is true
manualLinkOnly bool No false Show only manual linking options

AeroSyncNavigatorObserver

Parameter Type Required Description
deeplink String Yes Must match the deeplink passed to AeroSyncWidget

AeroSyncNavigatorObserver is mobile-only and has no effect on Flutter Web.

Callback Events

Callback Description
onSuccess Bank connection completed successfully — receives account details
onClose User closed the widget
onEvent General widget events and page navigation
onError Error occurred during the process
onLoad Widget finished loading

Success Response Format

Store onSuccess() data attributes to authenticate with the AeroSync API:

{
  "type": "pageSuccess",
  "payload": {
    "user_id": "a08905dae1d74c9ea021d325d8de654f",
    "user_password": "7f9946f5e2e34f61a59f2f3c00535118",
    "ClientName": "Aeropay",
    "FILoginAcctId": 113786059
  }
}

Platform-Specific Notes

iOS

  • Deployment target: iOS 11.0+
  • All dependencies support Swift Package Manager — no CocoaPods step required

Android

  • Minimum SDK version: 21
  • Add internet permission to android/app/src/main/AndroidManifest.xml: 
    <uses-permission android:name="android.permission.INTERNET" />

Flutter Web

  • No additional packages or configuration needed — the SDK detects kIsWeb and uses the appropriate path automatically
  • AeroSyncNavigatorObserver is not needed on web
  • deeplink is silently omitted from the widget URL on web

Troubleshooting

  1. Widget not loading: Verify your token is valid and not expired
  2. OAuth return drops user to home screen (mobile): Ensure AeroSyncNavigatorObserver is added to MaterialApp.navigatorObservers
  3. Popup blocked (web): The widget must be opened from a button tap. Allow popups for your domain in browser settings if needed
  4. OAuth opens as a tab instead of popup (web): Switch to widgetLaunchType: 'systemBrowser' — the iframe (host) mode is subject to Chrome's cross-origin popup restriction
  5. Build errors: Run flutter clean and flutter pub get

Support

For technical support and questions, please contact our development team.

License

This SDK is proprietary software. Please refer to your license agreement for usage terms.

Libraries

aerosync_flutter_sdk
constants