Dart entrypoint, entrypoint arguments, initial route, and app bundle path

The Dart entrypoint executed within this Activity is "main()" by default. To change the entrypoint that a FlutterActivity executes, subclass FlutterActivity and override getDartEntrypointFunctionName() . For non-main Dart entrypoints to not be tree-shaken away, you need to annotate those functions with @pragma('vm:entry-point') in Dart.

The Dart entrypoint arguments will be passed as a list of string to Dart's entrypoint function. It can be passed using a FlutterActivity.NewEngineIntentBuilder via FlutterActivity.NewEngineIntentBuilder.dartEntrypointArgs .

The Flutter route that is initially loaded within this Activity is "/". The initial route may be specified explicitly by passing the name of the route as a String in FlutterActivityLaunchConfigs.EXTRA_INITIAL_ROUTE , e.g., "my/deep/link".

The initial route can each be controlled using a FlutterActivity.NewEngineIntentBuilder via FlutterActivity.NewEngineIntentBuilder.initialRoute .

The app bundle path, Dart entrypoint, Dart entrypoint arguments, and initial route can also be controlled in a subclass of FlutterActivity by overriding their respective methods:

The Dart entrypoint and app bundle path are not supported as Intent parameters since your Dart library entrypoints are your private APIs and Intents are invocable by other processes.

Using a cached FlutterEngine

FlutterActivity can be used with a cached FlutterEngine instead of creating a new one. Use withCachedEngine(String) to build a FlutterActivity Intent that is configured to use an existing, cached FlutterEngine . FlutterEngineCache is the cache that is used to obtain a given cached FlutterEngine . You must create and put a FlutterEngine into the FlutterEngineCache yourself before using the withCachedEngine(String) builder. An IllegalStateException will be thrown if a cached engine is requested but does not exist in the cache.

When using a cached FlutterEngine , that FlutterEngine should already be executing Dart code, which means that the Dart entrypoint and initial route have already been defined. Therefore, FlutterActivity.CachedEngineIntentBuilder does not offer configuration of these properties.

It is generally recommended to use a cached FlutterEngine to avoid a momentary delay when initializing a new FlutterEngine . The two exceptions to using a cached FlutterEngine are:

See https://flutter.dev/docs/development/add-to-app/performance for additional performance explorations on engine loading.

The following illustrates how to pre-warm and cache a FlutterEngine : // Create and pre-warm a FlutterEngine. FlutterEngineGroup group = new FlutterEngineGroup(context); FlutterEngine flutterEngine = group.createAndRunDefaultEngine(context); flutterEngine.getDartExecutor().executeDartEntrypoint(DartEntrypoint.createDefault()); // Cache the pre-warmed FlutterEngine in the FlutterEngineCache. FlutterEngineCache.getInstance().put("my_engine", flutterEngine);

Alternatives to FlutterActivity

If Flutter is needed in a location that cannot use an Activity , consider using a FlutterFragment . Using a FlutterFragment requires forwarding some calls from an Activity to the FlutterFragment .

If Flutter is needed in a location that can only use a View , consider using a FlutterView . Using a FlutterView requires forwarding some calls from an Activity , as well as forwarding lifecycle calls from an Activity or a Fragment .

Launch Screen

FlutterActivity supports the display of an Android "launch screen", which is displayed while the Android application loads. It is only applicable if FlutterActivity is the first Activity displayed upon loading the app.

Prior to Flutter 2.5, FlutterActivity supported the display of a Flutter-specific "splash screen" that would be displayed after the launch screen passes. This has since been deprecated. If a launch screen is specified, it will automatically persist for as long as it takes Flutter to initialize and render its first frame.

Use Android themes to display a launch screen. Create two themes: a launch theme and a normal theme. In the launch theme, set windowBackground to the desired Drawable for the launch screen. In the normal theme, set windowBackground to any desired background color that should normally appear behind your Flutter content. In most cases this background color will never be seen, but for possible transition edge cases it is a good idea to explicitly replace the launch screen window background with a neutral color.

Do not change aspects of system chrome between a launch theme and normal theme. Either define both themes to be fullscreen or not, and define both themes to display the same status bar and navigation bar settings. To adjust system chrome once the Flutter app renders, use platform channels to instruct Android to do so at the appropriate time. This will avoid any jarring visual changes during app startup.

In the AndroidManifest.xml, set the theme of FlutterActivity to the defined launch theme. In the metadata section for FlutterActivity , defined the following reference to your normal theme:

<meta-data android:name="io.flutter.embedding.android.NormalTheme" android:resource="@style/YourNormalTheme" />

With themes defined, and AndroidManifest.xml updated, Flutter displays the specified launch screen until the Android application is initialized.

Alternative Activity FlutterFragmentActivity is also available, which is similar to FlutterActivity but it extends FragmentActivity . You should use FlutterActivity , if possible, but if you need a FragmentActivity then you should use FlutterFragmentActivity .