initializeRollaSDK function

Future<void> initializeRollaSDK()

Entry point for the Rolla SDK module when embedded in native apps.

This module follows Flutter's official Add-to-App pattern: https://docs.flutter.dev/add-to-app

How it works:

  1. Native app creates Flutter engine and runs this main() function
  2. Flutter shows a loading screen while waiting for initialization
  3. Native app calls MethodChannel('rolla_sdk/init').invokeMethod('initialize', {...})
  4. SDK initializes with provided token/userId/config
  5. Flutter renders RollaSdkHome which provides the full SDK experience
  6. User interacts with SDK modules (all navigation handled by GoRouter)
  7. User closes SDK (or logs out), Flutter notifies native via method channel

Architecture:

This file is intentionally minimal - it's just a thin shell for native integration. ALL SDK UI logic lives in RollaSdkHome which is the single source of truth for both Flutter plugin and native add-to-app integrations.

For Flutter plugin integration, host apps use RollaSdkHome directly. For native integration, this main.dart wraps RollaSdkHome and handles the method channel communication. Initialize the Rolla SDK for native add-to-app integration.

This sets up:

  • Flutter bindings
  • Method channel handler (FIRST - critical for native communication)
  • Portrait orientation lock (fire-and-forget to avoid blocking on cached engines)
  • BLoC observer for debugging

Note: Service locator (GetIt) is NOT initialized here. It's initialized when native calls the 'initialize' method via MethodChannel. This avoids a race condition where both main() and method channel could try to initialize simultaneously.

Authentication and modules are also initialized via MethodChannel.

Implementation

/// Initialize the Rolla SDK for native add-to-app integration.
///
/// This sets up:
/// - Flutter bindings
/// - Method channel handler (FIRST - critical for native communication)
/// - Portrait orientation lock (fire-and-forget to avoid blocking on cached engines)
/// - BLoC observer for debugging
///
/// Note: Service locator (GetIt) is NOT initialized here. It's initialized when
/// native calls the 'initialize' method via MethodChannel. This avoids a race
/// condition where both main() and method channel could try to initialize
/// simultaneously.
///
/// Authentication and modules are also initialized via MethodChannel.
Future<void> initializeRollaSDK() async {
  WidgetsFlutterBinding.ensureInitialized();

  // CRITICAL: Register method channel handler FIRST
  // This sets up the listener before native can send messages
  MethodChannelHandler.instance;

  // NOTE: Don't await setPreferredOrientations - it can hang on some devices
  // when there's no Activity attached (cached engine mode). Fire-and-forget.
  SystemChrome.setPreferredOrientations([
    DeviceOrientation.portraitUp,
  ]);

  Bloc.observer = AppBlocObserver();

  // Quiet a couple of high-volume, harmless Mapbox native log lines that
  // otherwise fire on nearly every frame in debug builds.
  installMapboxLogFilter();

  // NOTE: setupServiceLocator() is intentionally NOT called here.
  // It's called by RollaSDK.initialize/initializeWithToken when native
  // sends the 'initialize' message via method channel. This ensures a
  // single, clean initialization path and avoids race conditions.
}