Package io.flutter.embedding.android

Class FlutterActivity

java.lang.Object
android.content.Context
android.content.ContextWrapper
android.view.ContextThemeWrapper
android.app.Activity
io.flutter.embedding.android.FlutterActivity
All Implemented Interfaces:
ComponentCallbacks, ComponentCallbacks2, KeyEvent.Callback, LayoutInflater.Factory, LayoutInflater.Factory2, View.OnCreateContextMenuListener, Window.Callback, androidx.lifecycle.LifecycleOwner, FlutterEngineConfigurator, FlutterEngineProvider, PlatformPlugin.PlatformPluginDelegate
public class FlutterActivity extends Activity implements androidx.lifecycle.LifecycleOwner
Activity which displays a fullscreen Flutter UI.

FlutterActivity is the simplest and most direct way to integrate Flutter within an Android app.

FlutterActivity responsibilities

FlutterActivity maintains the following responsibilities:

  • Displays an Android launch screen.
  • Configures the status bar appearance.
  • Chooses the Dart execution app bundle path, entrypoint and entrypoint arguments.
  • Chooses Flutter's initial route.
  • Renders Activity transparently, if desired.
  • Offers hooks for subclasses to provide and configure a FlutterEngine.
  • Save and restore instance state, see #shouldRestoreAndSaveState();

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:

  • When FlutterActivity is the first Activity displayed by the app, because pre-warming a FlutterEngine would have no impact in this situation.
  • When you are unsure when/if you will need to display a Flutter experience.

See https://docs.flutter.cn/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.

  • Field Details

    • FLUTTER_VIEW_ID

      public static final int FLUTTER_VIEW_ID
      The ID of the FlutterView created by this activity.

      This ID can be used to lookup FlutterView in the Android view hierarchy. For more, see View.findViewById(int).

    • delegate

      @VisibleForTesting protected io.flutter.embedding.android.FlutterActivityAndFragmentDelegate delegate

  • Constructor Details

    • FlutterActivity

      public FlutterActivity()

  • Method Details

    • createDefaultIntent

      @NonNull public static Intent createDefaultIntent(@NonNull Context launchContext)
      Creates an Intent that launches a FlutterActivity, which creates a FlutterEngine that executes a main() Dart entrypoint, and displays the "/" route as Flutter's initial route.

      Consider using the withCachedEngine(String) Intent builder to control when the FlutterEngine should be created in your application.

      Parameters:
      launchContext - The launch context. e.g. An Activity.
      Returns:
      The default intent.

    • withNewEngine

      @NonNull public static FlutterActivity.NewEngineIntentBuilder withNewEngine()
      Creates an FlutterActivity.NewEngineIntentBuilder, which can be used to configure an Intent to launch a FlutterActivity that internally creates a new FlutterEngine using the desired Dart entrypoint, initial route, etc.
      Returns:
      The engine intent builder.

    • withCachedEngine

      public static FlutterActivity.CachedEngineIntentBuilder withCachedEngine(@NonNull String cachedEngineId)
      Creates a FlutterActivity.CachedEngineIntentBuilder, which can be used to configure an Intent to launch a FlutterActivity that internally uses an existing FlutterEngine that is cached in FlutterEngineCache.
      Parameters:
      cachedEngineId - A cached engine ID.
      Returns:
      The builder.

    • withNewEngineInGroup

      public static FlutterActivity.NewEngineInGroupIntentBuilder withNewEngineInGroup(@NonNull String engineGroupId)
      Creates a FlutterActivity.NewEngineInGroupIntentBuilder, which can be used to configure an Intent to launch a FlutterActivity by internally creating a FlutterEngine from an existing FlutterEngineGroup cached in a specified FlutterEngineGroupCache. 
      
 // Create a FlutterEngineGroup, such as in the onCreate method of the Application.
 FlutterEngineGroup engineGroup = new FlutterEngineGroup(this);
 FlutterEngineGroupCache.getInstance().put("my_cached_engine_group_id", engineGroup);

 // Start a FlutterActivity with the FlutterEngineGroup by creating an intent with withNewEngineInGroup
 Intent intent = FlutterActivity.withNewEngineInGroup("my_cached_engine_group_id")
     .dartEntrypoint("custom_entrypoint")
     .initialRoute("/custom/route")
     .backgroundMode(BackgroundMode.transparent)
     .build(context);
 startActivity(intent);
      Parameters:
      engineGroupId - A cached engine group ID.
      Returns:
      The builder.

    • getExclusiveAppComponent

      public ExclusiveAppComponent<Activity> getExclusiveAppComponent()
      Returns the Android App Component exclusively attached to FlutterEngine.

    • onCreate

      protected void onCreate(@Nullable Bundle savedInstanceState)
      Overrides:
      onCreate in class Activity

    • registerOnBackInvokedCallback

      @VisibleForTesting public void registerOnBackInvokedCallback()
      Registers the callback with OnBackInvokedDispatcher to capture back navigation gestures and pass them to the framework.

      This replaces the deprecated onBackPressed method override in order to support API 33's predictive back navigation feature.

      The callback must be unregistered in order to prevent unpredictable behavior once outside the Flutter app.

    • unregisterOnBackInvokedCallback

      @VisibleForTesting public void unregisterOnBackInvokedCallback()
      Unregisters the callback from OnBackInvokedDispatcher.

      This should be called when the activity is no longer in use to prevent unpredictable behavior such as being stuck and unable to press back.

    • getOnBackInvokedCallback

      @VisibleForTesting protected OnBackInvokedCallback getOnBackInvokedCallback()

    • setFrameworkHandlesBack

      public void setFrameworkHandlesBack(boolean frameworkHandlesBack)
      Description copied from interface: PlatformPlugin.PlatformPluginDelegate
      The Flutter application would or would not like to handle navigation pop events itself.

      Relevant for registering and unregistering the app's OnBackInvokedCallback for the Predictive Back feature, for example as in FlutterActivity.

      Specified by:
      setFrameworkHandlesBack in interface PlatformPlugin.PlatformPluginDelegate

    • onStart

      protected void onStart()
      Overrides:
      onStart in class Activity

    • onResume

      protected void onResume()
      Overrides:
      onResume in class Activity

    • onPostResume

      public void onPostResume()
      Overrides:
      onPostResume in class Activity

    • onPause

      protected void onPause()
      Overrides:
      onPause in class Activity

    • onStop

      protected void onStop()
      Overrides:
      onStop in class Activity

    • onSaveInstanceState

      protected void onSaveInstanceState(Bundle outState)
      Overrides:
      onSaveInstanceState in class Activity

    • release

      @VisibleForTesting public void release()
      Irreversibly release this activity's control of the FlutterEngine and its subcomponents.

      Calling will disconnect this activity's view from the Flutter renderer, disconnect this activity from plugins' ActivityControlSurface, and stop system channel messages from this activity.

      After calling, this activity should be disposed immediately and not be re-used.

    • detachFromFlutterEngine

      public void detachFromFlutterEngine()

    • onDestroy

      protected void onDestroy()
      Overrides:
      onDestroy in class Activity

    • onActivityResult

      protected void onActivityResult(int requestCode, int resultCode, Intent data)
      Overrides:
      onActivityResult in class Activity

    • onNewIntent

      protected void onNewIntent(@NonNull Intent intent)
      Overrides:
      onNewIntent in class Activity

    • onBackPressed

      public void onBackPressed()
      Overrides:
      onBackPressed in class Activity

    • startBackGesture

      @RequiresApi(34) public void startBackGesture(@NonNull BackEvent backEvent)

    • updateBackGestureProgress

      @RequiresApi(34) public void updateBackGestureProgress(@NonNull BackEvent backEvent)

    • commitBackGesture

      @RequiresApi(34) public void commitBackGesture()

    • cancelBackGesture

      @RequiresApi(34) public void cancelBackGesture()

    • onRequestPermissionsResult

      public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults)
      Overrides:
      onRequestPermissionsResult in class Activity

    • onUserLeaveHint

      public void onUserLeaveHint()
      Overrides:
      onUserLeaveHint in class Activity

    • onWindowFocusChanged

      public void onWindowFocusChanged(boolean hasFocus)
      Specified by:
      onWindowFocusChanged in interface Window.Callback
      Overrides:
      onWindowFocusChanged in class Activity

    • onTrimMemory

      public void onTrimMemory(int level)
      Specified by:
      onTrimMemory in interface ComponentCallbacks2
      Overrides:
      onTrimMemory in class Activity

    • getContext

      @NonNull public Context getContext()
      FlutterActivityAndFragmentDelegate.Host method that is used by FlutterActivityAndFragmentDelegate to obtain a Context reference as needed.

    • getActivity

      @NonNull public Activity getActivity()
      FlutterActivityAndFragmentDelegate.Host method that is used by FlutterActivityAndFragmentDelegate to obtain an Activity reference as needed. This reference is used by the delegate to instantiate a FlutterView, a PlatformPlugin, and to determine if the Activity is changing configurations.

    • getLifecycle

      @NonNull public androidx.lifecycle.Lifecycle getLifecycle()
      FlutterActivityAndFragmentDelegate.Host method that is used by FlutterActivityAndFragmentDelegate to obtain a Lifecycle reference as needed. This reference is used by the delegate to provide Flutter plugins with access to lifecycle events.
      Specified by:
      getLifecycle in interface androidx.lifecycle.LifecycleOwner

    • getFlutterShellArgs

      @NonNull public FlutterShellArgs getFlutterShellArgs()
      FlutterActivityAndFragmentDelegate.Host method that is used by FlutterActivityAndFragmentDelegate to obtain Flutter shell arguments when initializing Flutter.

    • getCachedEngineId

      @Nullable public String getCachedEngineId()
      Returns the ID of a statically cached FlutterEngine to use within this FlutterActivity, or null if this FlutterActivity does not want to use a cached FlutterEngine.

    • getCachedEngineGroupId

      @Nullable public String getCachedEngineGroupId()
      Returns the ID of a statically cached FlutterEngineGroup to use within this FlutterActivity, or null if this FlutterActivity does not want to use a cached FlutterEngineGroup.

    • shouldDestroyEngineWithHost

      public boolean shouldDestroyEngineWithHost()
      Returns false if the FlutterEngine backing this FlutterActivity should outlive this FlutterActivity, or true to be destroyed when the FlutterActivity is destroyed.

      The default value is true in cases where FlutterActivity created its own FlutterEngine, and false in cases where a cached FlutterEngine was provided.

    • getDartEntrypointFunctionName

      @NonNull public String getDartEntrypointFunctionName()
      The Dart entrypoint that will be executed as soon as the Dart snapshot is loaded.

      This preference can be controlled with 2 methods:

      1. Pass a boolean as FlutterActivityLaunchConfigs.EXTRA_DART_ENTRYPOINT with the launching Intent, or
      2. Set a <meta-data> called FlutterActivityLaunchConfigs.DART_ENTRYPOINT_META_DATA_KEY within the Android manifest definition for this FlutterActivity
      If both preferences are set, the Intent preference takes priority.

      Subclasses may override this method to directly control the Dart entrypoint.

    • getDartEntrypointArgs

      @Nullable public List<String> getDartEntrypointArgs()
      The Dart entrypoint arguments will be passed as a list of string to Dart's entrypoint function.

      A value of null means do not pass any arguments to Dart's entrypoint function.

      Subclasses may override this method to directly control the Dart entrypoint arguments.

    • getDartEntrypointLibraryUri

      @Nullable public String getDartEntrypointLibraryUri()
      The Dart library URI for the entrypoint that will be executed as soon as the Dart snapshot is loaded.

      Example value: "package:foo/bar.dart"

      This preference can be controlled by setting a <meta-data> called FlutterActivityLaunchConfigs.DART_ENTRYPOINT_URI_META_DATA_KEY within the Android manifest definition for this FlutterActivity.

      A value of null means use the default root library.

      Subclasses may override this method to directly control the Dart entrypoint uri.

    • getInitialRoute

      public String getInitialRoute()
      The initial route that a Flutter app will render upon loading and executing its Dart code.

      This preference can be controlled with 2 methods:

      1. Pass a boolean as FlutterActivityLaunchConfigs.EXTRA_INITIAL_ROUTE with the launching Intent, or
      2. Set a <meta-data> called FlutterActivityLaunchConfigs.INITIAL_ROUTE_META_DATA_KEY for this Activity in the Android manifest.
      If both preferences are set, the Intent preference takes priority.

      The reason that a <meta-data> preference is supported is because this Activity might be the very first Activity launched, which means the developer won't have control over the incoming Intent.

      Subclasses may override this method to directly control the initial route.

      If this method returns null and the shouldHandleDeeplinking returns true, the initial route is derived from the Intent through the Intent.getData() instead.

    • getAppBundlePath

      @NonNull public String getAppBundlePath()
      A custom path to the bundle that contains this Flutter app's resources, e.g., Dart code snapshots.

      When this FlutterActivity is run by Flutter tooling and a data String is included in the launching Intent, that data String is interpreted as an app bundle path.

      When otherwise unspecified, the value is null, which defaults to the app bundle path defined in FlutterLoader.findAppBundlePath().

      Subclasses may override this method to return a custom app bundle path.

    • getRenderMode

      @NonNull public RenderMode getRenderMode()
      FlutterActivityAndFragmentDelegate.Host method that is used by FlutterActivityAndFragmentDelegate to obtain the desired RenderMode that should be used when instantiating a FlutterView.

    • getTransparencyMode

      @NonNull public TransparencyMode getTransparencyMode()
      FlutterActivityAndFragmentDelegate.Host method that is used by FlutterActivityAndFragmentDelegate to obtain the desired TransparencyMode that should be used when instantiating a FlutterView.

    • getBackgroundMode

      @NonNull protected FlutterActivityLaunchConfigs.BackgroundMode getBackgroundMode()
      The desired window background mode of this Activity, which defaults to FlutterActivityLaunchConfigs.BackgroundMode.opaque.
      Returns:
      The background mode.

    • provideFlutterEngine

      @Nullable public FlutterEngine provideFlutterEngine(@NonNull Context context)
      Hook for subclasses to easily provide a custom FlutterEngine.

      This hook is where a cached FlutterEngine should be provided, if a cached FlutterEngine is desired.

      Specified by:
      provideFlutterEngine in interface FlutterEngineProvider
      Parameters:
      context - The current context. e.g. An activity.
      Returns:
      The Flutter engine.

    • getFlutterEngine

      @Nullable protected FlutterEngine getFlutterEngine()
      Hook for subclasses to obtain a reference to the FlutterEngine that is owned by this FlutterActivity.
      Returns:
      The Flutter engine.

    • getMetaData

      @Nullable protected Bundle getMetaData() throws PackageManager.NameNotFoundException
      Retrieves the meta data specified in the AndroidManifest.xml.
      Returns:
      The meta data.
      Throws:
      PackageManager.NameNotFoundException - if a package with the given name cannot be found on the system.

    • providePlatformPlugin

      @Nullable public PlatformPlugin providePlatformPlugin(@Nullable Activity activity, @NonNull FlutterEngine flutterEngine)

    • configureFlutterEngine

      public void configureFlutterEngine(@NonNull FlutterEngine flutterEngine)
      Hook for subclasses to easily configure a FlutterEngine.

      This method is called after provideFlutterEngine(Context).

      All plugins listed in the app's pubspec are registered in the base implementation of this method unless the FlutterEngine for this activity was externally created. To avoid the automatic plugin registration for implicitly created FlutterEngines, override this method without invoking super(). To keep automatic plugin registration and further configure the FlutterEngine, override this method, invoke super(), and then configure the FlutterEngine as desired.

      Specified by:
      configureFlutterEngine in interface FlutterEngineConfigurator
      Parameters:
      flutterEngine - The Flutter engine.

    • cleanUpFlutterEngine

      public void cleanUpFlutterEngine(@NonNull FlutterEngine flutterEngine)
      Hook for the host to cleanup references that were established in configureFlutterEngine(FlutterEngine) before the host is destroyed or detached.

      This method is called in onDestroy().

      Specified by:
      cleanUpFlutterEngine in interface FlutterEngineConfigurator
      Parameters:
      flutterEngine - The Flutter engine.

    • shouldAttachEngineToActivity

      public boolean shouldAttachEngineToActivity()
      Hook for subclasses to control whether or not the FlutterFragment within this Activity automatically attaches its FlutterEngine to this Activity.

      This property is controlled with a protected method instead of an Intent argument because the only situation where changing this value would help, is a situation in which FlutterActivity is being subclassed to utilize a custom and/or cached FlutterEngine.

      Defaults to true.

      Control surfaces are used to provide Android resources and lifecycle events to plugins that are attached to the FlutterEngine. If shouldAttachEngineToActivity is true, then this FlutterActivity will connect its FlutterEngine to itself, along with any plugins that are registered with that FlutterEngine. This allows plugins to access the Activity, as well as receive Activity-specific calls, e.g. Activity.onNewIntent(Intent). If shouldAttachEngineToActivity is false, then this FlutterActivity will not automatically manage the connection between its FlutterEngine and itself. In this case, plugins will not be offered a reference to an Activity or its OS hooks.

      Returning false from this method does not preclude a FlutterEngine from being attaching to a FlutterActivity - it just prevents the attachment from happening automatically. A developer can choose to subclass FlutterActivity and then invoke ActivityControlSurface.attachToActivity(ExclusiveAppComponent, Lifecycle) and ActivityControlSurface.detachFromActivity() at the desired times.

      One reason that a developer might choose to manually manage the relationship between the Activity and FlutterEngine is if the developer wants to move the FlutterEngine somewhere else. For example, a developer might want the FlutterEngine to outlive this FlutterActivity so that it can be used later in a different Activity. To accomplish this, the FlutterEngine may need to be disconnected from this FlutterActivity at an unusual time, preventing this FlutterActivity from correctly managing the relationship between the FlutterEngine and itself.

    • shouldHandleDeeplinking

      public boolean shouldHandleDeeplinking()
      Whether to handle the deeplinking from the Intent automatically if the getInitialRoute returns null.

      The default implementation looks <meta-data> called FlutterActivityLaunchConfigs.HANDLE_DEEPLINKING_META_DATA_KEY within the Android manifest definition for this FlutterActivity.

    • onFlutterSurfaceViewCreated

      public void onFlutterSurfaceViewCreated(@NonNull FlutterSurfaceView flutterSurfaceView)

    • onFlutterTextureViewCreated

      public void onFlutterTextureViewCreated(@NonNull FlutterTextureView flutterTextureView)

    • onFlutterUiDisplayed

      public void onFlutterUiDisplayed()

    • onFlutterUiNoLongerDisplayed

      public void onFlutterUiNoLongerDisplayed()

    • shouldRestoreAndSaveState

      public boolean shouldRestoreAndSaveState()

    • shouldDispatchAppLifecycleState

      public boolean shouldDispatchAppLifecycleState()
      Give the host application a chance to take control of the app lifecycle events.

      Return false means the host application dispatches these app lifecycle events, while return true means the engine dispatches these events.

      Defaults to true.

    • attachToEngineAutomatically

      public boolean attachToEngineAutomatically()
      Whether to automatically attach the FlutterView to the engine.

      Returning false means that the task of attaching the FlutterView to the engine will be taken over by the host application.

      Defaults to true.

    • popSystemNavigator

      public boolean popSystemNavigator()
      Description copied from interface: PlatformPlugin.PlatformPluginDelegate
      Allow implementer to customize the behavior needed when the Flutter framework calls to pop the Android-side navigation stack.
      Specified by:
      popSystemNavigator in interface PlatformPlugin.PlatformPluginDelegate
      Returns:
      true if the implementation consumed the pop signal. If false, a default behavior of finishing the activity or sending the signal to OnBackPressedDispatcher will be executed.

    • updateSystemUiOverlays

      public void updateSystemUiOverlays()