Skip to main content

UIScene adoption

Learn how to migrate your Flutter iOS app, add-to-app integration, or plugin to Apple's required UIScene lifecycle.

Summary

#

Apple now requires iOS developers to adopt the UIScene lifecycle. This migration has implications for the app launch sequence and app lifecycle.

Background

#

During WWDC25, Apple announced the following:

In the release following iOS 26, any UIKit app built with the latest SDK will be required to use the UIScene life cycle, otherwise it will not launch.

To adopt the UIScene lifecycle, follow the guide that corresponds to your use case:

Migrating to UIScene shifts the role of the AppDelegate: the UISceneDelegate now handles the UI lifecycle, while the AppDelegate remains responsible for process events and the overall application lifecycle.

Move all UI-related logic from the AppDelegate to the corresponding UISceneDelegate methods. After you migrate to UIScene, UIKit no longer calls AppDelegate methods related to UI state.

Migrate a Flutter app

#

Auto-migrate

#

As of Flutter 3.41, UIScene is supported by default. If your AppDelegate hasn't been customized, the Flutter CLI automatically migrates your app.

To trigger the migration, build or run your app with the flutter run or flutter build ios commands. If the migration succeeds, the CLI outputs Finished migration to UIScene lifecycle and no further action is required. Otherwise, the CLI warns you and provides instructions to migrate manually.

Migrate AppDelegate

#

Previously, Flutter plugins were registered in application:didFinishLaunchingWithOptions:. To accommodate the new app launch sequence, you must now register plugins in a new didInitializeImplicitFlutterEngine callback.

  1. Conform your AppDelegate to the FlutterImplicitEngineDelegate protocol and move the GeneratedPluginRegistrant registration to didInitializeImplicitFlutterEngine.

    my_app/ios/Runner/AppDelegate.swift
    swift
    @objc class AppDelegate: FlutterAppDelegate {
@objc class AppDelegate: FlutterAppDelegate, FlutterImplicitEngineDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
​
  func didInitializeImplicitFlutterEngine(_ engineBridge: FlutterImplicitEngineBridge) {
    GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry)
  }
}
    my_app/ios/Runner/AppDelegate.h
    objc
    @interface AppDelegate : FlutterAppDelegate
@interface AppDelegate : FlutterAppDelegate <FlutterImplicitEngineDelegate>
    my_app/ios/Runner/AppDelegate.m
    objc
    - (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [GeneratedPluginRegistrant registerWithRegistry:self];
  return [super application:application didFinishLaunchingWithOptions:launchOptions];
}
​
- (void)didInitializeImplicitFlutterEngine:(NSObject<FlutterImplicitEngineBridge>*)engineBridge {
  [GeneratedPluginRegistrant registerWithRegistry:engineBridge.pluginRegistry];
}

  2. If applicable, create method channels and platform views in didInitializeImplicitFlutterEngine.

    If you previously created method channels or platform views in application:didFinishLaunchingWithOptions:, move that logic to didInitializeImplicitFlutterEngine.

    swift
    func didInitializeImplicitFlutterEngine(_ engineBridge: FlutterImplicitEngineBridge) {
  // Register plugins with `engineBridge.pluginRegistry`:
  GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry)
​
  // Create method channels with `engineBridge.applicationRegistrar.messenger()`:
  let batteryChannel = FlutterMethodChannel(
    name: "samples.flutter.dev/battery",
    binaryMessenger: engineBridge.applicationRegistrar.messenger()
  )
​
  // Create platform views with `engineBridge.applicationRegistrar.messenger()`:
  let factory = FLNativeViewFactory(messenger: engineBridge.applicationRegistrar.messenger())
}
    objc
    - (void)didInitializeImplicitFlutterEngine:(NSObject<FlutterImplicitEngineBridge>*)engineBridge {
  // Register plugins with `engineBridge.pluginRegistry`:
  [GeneratedPluginRegistrant registerWithRegistry:engineBridge.pluginRegistry];
​
  // Create method channels with `engineBridge.applicationRegistrar.messenger`:
  FlutterMethodChannel* batteryChannel = [FlutterMethodChannel
      methodChannelWithName:@"samples.flutter.dev/battery"
            binaryMessenger:engineBridge.applicationRegistrar.messenger];
​
  // Create platform views with `engineBridge.applicationRegistrar.messenger`:
  FLNativeViewFactory* factory =
      [[FLNativeViewFactory alloc] initWithMessenger:engineBridge.applicationRegistrar.messenger];
}

  3. Migrate any custom logic within application lifecycle events.

    Apple has deprecated application lifecycle events related to UI state. After you migrate to the UIScene lifecycle, UIKit no longer calls these events.

    If you used one of these deprecated APIs, such as applicationDidBecomeActive, you likely need to create a SceneDelegate and migrate to scene lifecycle events. To learn more, see Apple's documentation on migrating.

    If you implement your own SceneDelegate, you must subclass FlutterSceneDelegate or conform to the FlutterSceneLifeCycleProvider protocol. For examples, see Create or update a SceneDelegate.

Migrate Info.plist

#

To complete the migration to the UIScene lifecycle, add an Application Scene Manifest entry to your Info.plist.

As shown in Xcode's editor:

Xcode plist editor for UIApplicationSceneManifest

As XML:

Info.plist
xml 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>UIApplicationSceneManifest</key>
  <dict>
    <key>UIApplicationSupportsMultipleScenes</key>
    <false/>
    <key>UISceneConfigurations</key>
    <dict>
      <key>UIWindowSceneSessionRoleApplication</key>
      <array>
        <dict>
          <key>UISceneClassName</key>
          <string>UIWindowScene</string>
          <key>UISceneDelegateClassName</key>
          <string>FlutterSceneDelegate</string>
          <key>UISceneConfigurationName</key>
          <string>flutter</string>
          <key>UISceneStoryboardFile</key>
          <string>Main</string>
        </dict>
      </array>
    </dict>
  </dict>
</dict>
</plist>

Create a SceneDelegate (optional)

#

If you need access to the SceneDelegate, you can create one by subclassing FlutterSceneDelegate:

  1. Open your app in Xcode.

  2. Right-click the Runner folder, then select New Empty File.

    New Empty File option in Xcode

  3. Create your SceneDelegate class.

    For Swift projects, create a SceneDelegate.swift file:

    my_app/ios/Runner/SceneDelegate.swift
    swift
    import Flutter
import UIKit
​
class SceneDelegate: FlutterSceneDelegate {}

    For Objective-C projects, create a SceneDelegate.h and a SceneDelegate.m file:

    my_app/ios/Runner/SceneDelegate.h
    objc
    #import <Flutter/Flutter.h>
#import <UIKit/UIKit.h>
​
@interface SceneDelegate : FlutterSceneDelegate
​
@end
    my_app/ios/Runner/SceneDelegate.m
    objc
    #import "SceneDelegate.h"
​
@implementation SceneDelegate
​
@end

  4. In your Info.plist file, change the Delegate Class Name (UISceneDelegateClassName) value from FlutterSceneDelegate to your new class.

    For Swift projects, use $(PRODUCT_MODULE_NAME).SceneDelegate:

    Info.plist
    xml
    <key>UIApplicationSceneManifest</key>
<dict>
  <!-- ... -->
  <key>UISceneConfigurations</key>
  <dict>
    <key>UIWindowSceneSessionRoleApplication</key>
    <array>
      <dict>
        <!-- ... -->
        <key>UISceneDelegateClassName</key>
        <string>$(PRODUCT_MODULE_NAME).SceneDelegate</string>
        <!-- ... -->
      </dict>
    </array>
  </dict>
</dict>

    For Objective-C projects, use SceneDelegate:

    Info.plist
    xml
    <key>UIApplicationSceneManifest</key>
<dict>
  <!-- ... -->
  <key>UISceneConfigurations</key>
  <dict>
    <key>UIWindowSceneSessionRoleApplication</key>
    <array>
      <dict>
        <!-- ... -->
        <key>UISceneDelegateClassName</key>
        <string>SceneDelegate</string>
        <!-- ... -->
      </dict>
    </array>
  </dict>
</dict>

Migrate an add-to-app integration

#

Similar to the FlutterAppDelegate, the FlutterSceneDelegate is recommended but not required. The FlutterSceneDelegate forwards scene callbacks, such as openURL, to plugins such as local_auth.

Create or update a SceneDelegate

#
swift 
import UIKit
import Flutter
​
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
class SceneDelegate: FlutterSceneDelegate {
objc 
@interface SceneDelegate : UIResponder <UIWindowSceneDelegate>
@interface SceneDelegate : FlutterSceneDelegate

When using Flutter in a SwiftUI app, you can optionally use a FlutterAppDelegate to receive application events. To migrate it to receive UIScene events, make the following changes:

  1. Set the scene delegate to FlutterSceneDelegate in application:configurationForConnecting:options::

    swift
    @Observable
class AppDelegate: FlutterAppDelegate {
  ...
  override func application(
    _ application: UIApplication,
    configurationForConnecting connectingSceneSession: UISceneSession,
    options: UIScene.ConnectionOptions
  ) -> UISceneConfiguration {
    let configuration = UISceneConfiguration(
      name: nil,
      sessionRole: connectingSceneSession.role
    )
    configuration.delegateClass = FlutterSceneDelegate.self
    return configuration
  }
}

  2. If your app doesn't support multiple scenes, set Enable Multiple Scenes to NO under Application Scene Manifest in your target's Info properties. Multiple-scene support is enabled by default for SwiftUI apps.

    Xcode plist editor for UIApplicationSceneManifest

    If your app does support multiple scenes, see If your app supports multiple scenes for further instructions.

If you can't subclass FlutterSceneDelegate

#

If you can't subclass FlutterSceneDelegate, use the FlutterSceneLifeCycleProvider protocol and a FlutterPluginSceneLifeCycleDelegate object to forward scene lifecycle events to Flutter.

SceneDelegate.swift
swift 
import Flutter
import UIKit
​
class SceneDelegate: UIResponder, UIWindowSceneDelegate
class SceneDelegate: UIResponder, UIWindowSceneDelegate, FlutterSceneLifeCycleProvider
{
  var sceneLifeCycleDelegate: FlutterPluginSceneLifeCycleDelegate =
    FlutterPluginSceneLifeCycleDelegate()
​
  var window: UIWindow?
​
  func scene(
    _ scene: UIScene,
    willConnectTo session: UISceneSession,
    options connectionOptions: UIScene.ConnectionOptions
  ) {
    sceneLifeCycleDelegate.scene(
      scene,
      willConnectTo: session,
      options: connectionOptions
    )
  }
​
  func sceneDidDisconnect(_ scene: UIScene) {
    sceneLifeCycleDelegate.sceneDidDisconnect(scene)
  }
​
  func sceneWillEnterForeground(_ scene: UIScene) {
    sceneLifeCycleDelegate.sceneWillEnterForeground(scene)
  }
​
  func sceneDidBecomeActive(_ scene: UIScene) {
    sceneLifeCycleDelegate.sceneDidBecomeActive(scene)
  }
​
  func sceneWillResignActive(_ scene: UIScene) {
    sceneLifeCycleDelegate.sceneWillResignActive(scene)
  }
​
  func sceneDidEnterBackground(_ scene: UIScene) {
    sceneLifeCycleDelegate.sceneDidEnterBackground(scene)
  }
​
  func scene(
    _ scene: UIScene,
    openURLContexts URLContexts: Set<UIOpenURLContext>
  ) {
    sceneLifeCycleDelegate.scene(scene, openURLContexts: URLContexts)
  }
​
  func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    sceneLifeCycleDelegate.scene(scene, continue: userActivity)
  }
​
  func windowScene(
    _ windowScene: UIWindowScene,
    performActionFor shortcutItem: UIApplicationShortcutItem,
    completionHandler: @escaping (Bool) -> Void
  ) {
    sceneLifeCycleDelegate.windowScene(
      windowScene,
      performActionFor: shortcutItem,
      completionHandler: completionHandler
    )
  }
}
SceneDelegate.h
objc 
@interface SceneDelegate : UIResponder <UIWindowSceneDelegate>
@interface SceneDelegate : UIResponder <UIWindowSceneDelegate, FlutterSceneLifeCycleProvider>
​
@property(strong, nonatomic) UIWindow* window;
​
@property(nonatomic, strong) FlutterPluginSceneLifeCycleDelegate* sceneLifeCycleDelegate;
​
@end
SceneDelegate.m
objc 
@implementation SceneDelegate
​
- (instancetype)init {
  if (self = [super init]) {
    _sceneLifeCycleDelegate = [[FlutterPluginSceneLifeCycleDelegate alloc] init];
  }
  return self;
}
​
- (void)scene:(UIScene*)scene
    willConnectToSession:(UISceneSession*)session
                options:(UISceneConnectionOptions*)connectionOptions {
  [self.sceneLifeCycleDelegate scene:scene willConnectToSession:session options:connectionOptions];
}
​
- (void)sceneDidDisconnect:(UIScene*)scene {
  [self.sceneLifeCycleDelegate sceneDidDisconnect:scene];
}
​
- (void)sceneDidBecomeActive:(UIScene*)scene {
  [self.sceneLifeCycleDelegate sceneDidBecomeActive:scene];
}
​
- (void)sceneWillResignActive:(UIScene*)scene {
  [self.sceneLifeCycleDelegate sceneWillResignActive:scene];
}
​
- (void)sceneWillEnterForeground:(UIScene*)scene {
  [self.sceneLifeCycleDelegate sceneWillEnterForeground:scene];
}
​
- (void)sceneDidEnterBackground:(UIScene*)scene {
  [self.sceneLifeCycleDelegate sceneDidEnterBackground:scene];
}
​
- (void)scene:(UIScene*)scene openURLContexts:(NSSet<UIOpenURLContext*>*)URLContexts {
  [self.sceneLifeCycleDelegate scene:scene openURLContexts:URLContexts];
}
​
- (void)scene:(UIScene*)scene continueUserActivity:(NSUserActivity*)userActivity {
  [self.sceneLifeCycleDelegate scene:scene continueUserActivity:userActivity];
}
​
- (void)windowScene:(UIWindowScene*)windowScene
    performActionForShortcutItem:(UIApplicationShortcutItem*)shortcutItem
               completionHandler:(void (^)(BOOL))completionHandler {
  [self.sceneLifeCycleDelegate windowScene:windowScene
            performActionForShortcutItem:shortcutItem completionHandler:completionHandler];
}

If your app supports multiple scenes

#

Flutter doesn't fully support multiple scenes yet, but support is in progress.

Migrate a Flutter plugin

#

Not all plugins use lifecycle events. However, if your plugin does, migrate it to UIKit's scene-based lifecycle as follows:

  1. Update the Dart and Flutter SDK versions in your pubspec.yaml.

    The APIs required for this migration are available starting in Flutter 3.38:

    pubspec.yaml
    yaml
    environment:
  sdk: ^3.10.0
  flutter: ">=3.38.0"

  2. Adopt the FlutterSceneLifeCycleDelegate protocol.

    swift
    public final class MyPlugin: NSObject, FlutterPlugin {
public final class MyPlugin: NSObject, FlutterPlugin, FlutterSceneLifeCycleDelegate {
    objc
    @interface MyPlugin : NSObject<FlutterPlugin>
@interface MyPlugin : NSObject<FlutterPlugin, FlutterSceneLifeCycleDelegate>

  3. Register the plugin as a receiver of UISceneDelegate calls.

    To continue supporting apps that haven't yet migrated to the UIScene lifecycle, consider remaining registered to the application delegate and keeping the AppDelegate events as well.

    swift
    public static func register(with registrar: FlutterPluginRegistrar) {
  ...
  registrar.addApplicationDelegate(instance)
  registrar.addSceneDelegate(instance)
}
    objc
    + (void)registerWithRegistrar:(NSObject<FlutterPluginRegistrar> *)registrar {
  ...
  [registrar addApplicationDelegate:instance];
  [registrar addSceneDelegate:instance];
}

  4. Add the scene events that your plugin needs.

    Most AppDelegate UI events have a one-to-one replacement, as shown in the following table. For details about each event, visit Apple's documentation for UISceneDelegate and UIWindowSceneDelegate.

    App delegate methodScene delegate equivalent
    applicationDidBecomeActivesceneDidBecomeActive
    applicationWillResignActivesceneWillResignActive
    applicationWillEnterForegroundsceneWillEnterForeground
    applicationDidEnterBackgroundsceneDidEnterBackground
    application:continueUserActivity:restorationHandler:scene:continueUserActivity:
    application:performActionForShortcutItem:completionHandler:windowScene:performActionForShortcutItem:completionHandler:
    application:openURL:options:scene:openURLContexts:
    application:willFinishLaunchingWithOptions:scene:willConnectToSession:options:
    application:didFinishLaunchingWithOptions:scene:willConnectToSession:options:

    Once you identify the scene events that replace the application events your plugin relied on, implement the corresponding FlutterSceneLifeCycleDelegate methods. The following snippets show the signature of each scene event that FlutterSceneLifeCycleDelegate supports; implement only the ones your plugin needs.

    swift
    public func scene(
  _ scene: UIScene,
  willConnectTo session: UISceneSession,
  options connectionOptions: UIScene.ConnectionOptions?
) -> Bool { }
​
public func sceneDidDisconnect(_ scene: UIScene) { }
​
public func sceneWillEnterForeground(_ scene: UIScene) { }
​
public func sceneDidBecomeActive(_ scene: UIScene) { }
​
public func sceneWillResignActive(_ scene: UIScene) { }
​
public func sceneDidEnterBackground(_ scene: UIScene) { }
​
public func scene(
  _ scene: UIScene,
  openURLContexts URLContexts: Set<UIOpenURLContext>
) -> Bool { }
​
public func scene(
  _ scene: UIScene,
  continue userActivity: NSUserActivity
) -> Bool { }
​
public func windowScene(
  _ windowScene: UIWindowScene,
  performActionFor shortcutItem: UIApplicationShortcutItem,
  completionHandler: @escaping (Bool) -> Void
) -> Bool { }
    objc
    - (BOOL)scene:(UIScene*)scene
    willConnectToSession:(UISceneSession*)session
                 options:(nullable UISceneConnectionOptions*)connectionOptions { }
​
- (void)sceneDidDisconnect:(UIScene*)scene { }
​
- (void)sceneWillEnterForeground:(UIScene*)scene { }
​
- (void)sceneDidBecomeActive:(UIScene*)scene { }
​
- (void)sceneWillResignActive:(UIScene*)scene { }
​
- (void)sceneDidEnterBackground:(UIScene*)scene { }
​
- (BOOL)scene:(UIScene*)scene openURLContexts:(NSSet<UIOpenURLContext*>*)URLContexts { }
​
- (BOOL)scene:(UIScene*)scene continueUserActivity:(NSUserActivity*)userActivity { }
​
- (BOOL)windowScene:(UIWindowScene*)windowScene
    performActionForShortcutItem:(UIApplicationShortcutItem*)shortcutItem
               completionHandler:(void (^)(BOOL succeeded))completionHandler { }

  5. Move launch logic from application:willFinishLaunchingWithOptions: and application:didFinishLaunchingWithOptions: to scene:willConnectToSession:options:.

    Although application:willFinishLaunchingWithOptions: and application:didFinishLaunchingWithOptions: aren't deprecated, their launch options are nil after you migrate to the UIScene lifecycle. Move any logic that relies on the launch options to the scene:willConnectToSession:options: event.

  6. If your plugin uses an API that must be called before application:didFinishLaunchingWithOptions: completes, you should expose a public method that app developers can call directly in their AppDelegate.

    The following Apple APIs must be configured before app launch finishes:

    For example, to support BGTaskScheduler:

    swift
    // Plugin
​
public class BGTaskPlugin: NSObject, FlutterPlugin {
  public static let shared =  BGTaskPlugin()
  public static func register(with registrar: FlutterPluginRegistrar) {
    let channel = ...
    registrar.addMethodCallDelegate(shared, channel: channel)
    registrar.addApplicationDelegate(shared)
  }
  // A new API for apps to call in their `AppDelegate`'s `application:didFinishLaunchingWithOptions:`
  public func registerBackgroundHandler(identifier: String) {
    BGTaskScheduler.register(forTaskWithIdentifier: identifier, using: .main) { task in
      // Handle background task execution
    }
  }
  public func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [AnyHashable : Any] = [:]) -> Bool {
    BGTaskScheduler.register(forTaskWithIdentifier: identifier, using: .main) { task in
      // Handle background task execution
    }
    return true
  }
}
​
// App
​
class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    BGTaskPlugin.shared.registerBackgroundHandler(identifier: "com.example.task")
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}
    objc
    // Plugin
​
@interface BGTaskPlugin : NSObject <FlutterPlugin>
+ (instancetype)sharedInstance;
- (void)registerBackgroundHandlerWithIdentifier:(NSString *)identifier;
@end
​
@implementation BGTaskPlugin
​
+ (instancetype)sharedInstance {
  static BGTaskPlugin *sharedInstance = nil;
  static dispatch_once_t onceToken;
  dispatch_once(&onceToken, ^{
    sharedInstance = [[BGTaskPlugin alloc] init];
  });
  return sharedInstance;
}
​
+ (void)registerWithRegistrar:(NSObject<FlutterPluginRegistrar> *)registrar {
  FlutterMethodChannel *channel = ...
  [registrar addMethodCallDelegate:[BGTaskPlugin sharedInstance] channel:channel];
  [registrar addApplicationDelegate:[BGTaskPlugin sharedInstance]];
}
​
// A new API for apps to call in their `AppDelegate`'s `application:didFinishLaunchingWithOptions:`
- (void)registerBackgroundHandlerWithIdentifier:(NSString *)identifier {
  [[BGTaskScheduler sharedScheduler] registerForTaskWithIdentifier:identifier
                                                        usingQueue:dispatch_get_main_queue()
                                                     launchHandler:^(BGTask *task) {
    // Handle background task execution
  }];
}
​
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [[BGTaskScheduler sharedScheduler] registerForTaskWithIdentifier:identifier
                                                        usingQueue:dispatch_get_main_queue()
                                                     launchHandler:^(BGTask *task) {
    // Handle background task execution
  }];
  return YES;
}
@end
​
// App
​
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [[BGTaskPlugin sharedInstance] registerBackgroundHandlerWithIdentifier:@"com.example.task"];
  return [super application:application didFinishLaunchingWithOptions:launchOptions];
}
@end

    This change is required due to UIScene changing the app launch sequence. For apps that adopt UIScene, Flutter calls application:willFinishLaunchingWithOptions: and application:didFinishLaunchingWithOptions: during the scene:willConnectToSession:options: callback.

  7. Migrate other deprecated APIs to properly access the viewController, screen, or window.

    Deprecated APIUIScene replacement
    UIScreen mainScreenUIWindowScene screen
    UIApplication keyWindowUIWindowScene keyWindow
    UIApplication windowsUIWindowScene windows
    UIApplicationDelegate windowUIView window

    Because UIApplication.shared.delegate.window is nil after adopting UIScene, you should access the viewController via the plugin registrar's viewController property and retrieve the window or windowScene from there, as shown in the following examples.

    swift
    public class MyPlugin: NSObject, FlutterPlugin {
  var registrar: FlutterPluginRegistrar
​
  init(registrar: FlutterPluginRegistrar) {
    self.registrar = registrar
  }
​
  public static func register(with registrar: FlutterPluginRegistrar) {
    let instance = MyPlugin()
    let instance = MyPlugin(registrar: registrar)
  }
​
  func someMethod() {
    let screen = UIScreen.main
    let screen = self.registrar.viewController?.view.window?.windowScene?.screen
​
    let window = UIApplication.shared.delegate?.window
    let window = self.registrar.viewController?.view.window
​
    let keyWindow = UIApplication.shared.keyWindow
    if #available(iOS 15.0, *) {
      let keyWindow = self.registrar.viewController?.view.window?.windowScene?.keyWindow
    } else {
      let keyWindow = self.registrar.viewController?.view.window?.windowScene?.windows
        .filter({ $0.isKeyWindow }).first
    }
​
    let windows = UIApplication.shared.windows
    let windows = self.registrar.viewController?.view.window?.windowScene?.windows
  }
}
    objc
    @interface MyPlugin ()
@property(nonatomic, weak) NSObject<FlutterPluginRegistrar> *registrar;
- (instancetype)initWithRegistrar:(NSObject<FlutterPluginRegistrar> *)registrar;
@end
​
@implementation MyPlugin
​
- (instancetype)initWithRegistrar:(NSObject<FlutterPluginRegistrar> *)registrar {
  self = [super init];
  if (self) {
    _registrar = registrar;
  }
  return self;
}
​
+ (void)registerWithRegistrar:(NSObject<FlutterPluginRegistrar> *)registrar {
  MyPlugin *instance = [[MyPlugin alloc] init];
  MyPlugin *instance = [[MyPlugin alloc] initWithRegistrar:registrar];
}
​
- (void)someMethod {
  UIScreen *screen = [UIScreen mainScreen];
  UIScreen *screen = self.registrar.viewController.view.window.windowScene.screen;
​
  UIWindow *window = [UIApplication sharedApplication].delegate.window;
  UIWindow *window = self.registrar.viewController.view.window;
​
  UIWindow *keyWindow = [[UIApplication sharedApplication] keyWindow];
  if (@available(iOS 15.0, *)) {
    UIWindow *keyWindow = self.registrar.viewController.view.window.windowScene.keyWindow;
  } else {
    for (UIWindow *window in self.registrar.viewController.view.window.windowScene.windows) {
      if (window.isKeyWindow) {
        UIWindow *keyWindow = window;
      }
    }
  }
​
  NSArray<UIWindow *> *windows = [UIApplication sharedApplication].windows;
  NSArray<UIWindow *> *windows = self.registrar.viewController.view.window.windowScene.windows;
}

Bespoke FlutterViewController usage

#

If your app instantiates a FlutterViewController from storyboards in application:didFinishLaunchingWithOptions: for reasons other than creating platform channels, you must accommodate the new initialization order. To do so, use one of the following migration options:

  • Subclass FlutterViewController and put the logic in the subclass's awakeFromNib method.
  • Specify a UISceneDelegate in the Info.plist or in the UIApplicationDelegate, and put the logic in scene:willConnectToSession:options:. To learn more, check out Apple's documentation.

Example

#
swift 
@objc class MyViewController: FlutterViewController {
  override func awakeFromNib() {
    super.awakeFromNib()
    doSomethingWithFlutterViewController(self)
  }
}

Hide migration warning

#

To hide the Flutter CLI warning about migrating to UIScene, add the following to your pubspec.yaml:

pubspec.yaml
yaml 
flutter:
  config:
    enable-uiscene-migration: false

Temporarily disable UIScene

#

To temporarily disable UIScene support, add an underscore (_) in front of Application Scene Manifest in your Info.plist:

Xcode plist editor with an underscore in front of Application Scene Manifest

When you're ready to re-enable UIScene support, remove the underscore.

Timeline

#

Landed in version: 3.38.0-0.1.pre
In stable release: 3.38

Apple hasn't yet announced when it will enforce the UIScene requirement. Once Apple changes its warning to an assertion, Flutter apps that haven't adopted the UIScene lifecycle will crash on startup when built with the latest SDK.

References

#

Unless stated otherwise, the documentation on this site reflects Flutter 3.44.0. Page last updated on 2026-07-20. View source or report an issue.