Problem

There are many things that can break when migrating to scenes that can be unexpected to developers. For example:

• Accessing FlutterViewController in -[UIApplicateDelegate didFinishLaunchingWithOptions:] crashes
• Some application lifecycle events are no longer called: [iOS] Applifecycle events such as applicationDidBecomeActive and applicationWillResignActive are not called on master version #170037

In addition, after migrating to UIScenes, registering plugins in the application(_:didFinishLaunchingWithOptions:) function is no longer recommended. It will still work by using a new mechanism called FlutterLaunchEngine, but we want to move away from this.

Proposal 1

Instead of auto-migrating all Flutter apps, we should prompt the user to migrate. This will warn developers about the changes required and will provide helpful documentation.

To ensure your app continues to function correctly on upcoming iOS versions, UIScene lifecycle support will soon be required. Would you like to migrate your project now? [Y/N]

If "Y" and a customized AppDelegate is detected:

We've detected a customized AppDelegate in your project. To successfully migrate to UIScene, you may need to manually update your AppDelegate file. Failure to do so may lead to unexpected crashes or issues after migrating.

Please follow these instructions to update your AppDelegate: [link]

Would you like to proceed with the migration process? [Y/N]

If "N" at any time:

We strongly recommend migrating to UIScene. Failure to adopt UIScene will result in an assert in a future iOS version, which will prevent your app from launching.

For more information on UIScene migration, please refer to our documentation: [link]

Their response will be saved using flutter config:

• ios-uiscene-migration-status:
  • success
  • error
  • skipped
  • bypassed

If a user skips the migration process, each flutter run or flutter build for iOS will print a warning message, similar to Xcode. This warning will be built into the flutter assemble command so it will also appear in Xcode.

UIScene lifecycle will soon be required. Failure to adopt will result in an assert in the future. Run flutter config --reset ios-uiscene-migration-prompt and then run flutter build ios --config-only to complete the migration.

It’s possible that Flutter won’t be able to detect properly that they have already migrated their app to UIScene (you can migrate using Info.plist or adding code to AppDelegate). In that case, they can bypass the check.

flutter config --bypass-ios-uiscene-migration-prompt

After bypassing, they will not see anymore Flutter warnings or prompts in regards to UIScene migration.

If they opt to migrate, Flutter will add UIApplicationSceneManifest and its sub-settings to the app’s Info.plist.

It will additionally auto-migrate the AppDelegate file if it’s an exact match to the Flutter create template.

Due to the wide range of changes that may need to be made to the iOS code, the Flutter tool will not attempt other auto-migrations and will instead guide the developer to migrate manually with our documentation.

Manual migrations:

• Accessing FlutterViewController
• Registering plugins
• Registering app-level method channels
• Usage of deprecated APIs

If an error occurs while migrating (e.g. Flutter can’t update the Info.plist), Flutter will guide the developer to the documentation and display the following warning:

Flutter was unable to migrate your app to UIScene lifecycle. This will soon be required. Failure to adopt will result in an assert in the future. 

Please complete the following instructions to manually migrate: [link]

After migrating, run "flutter config --bypass-ios-uiscene-migration-prompt" to no longer see this warning.

Proposal 2

Instead of prompting the user and auto-migrating, simply provide a message that points to documentation on how to manually migrate.