Flutter 3.41 is live! Check out theFlutter 3.41 blog post!
Android ActivityControlSurface attachToActivity signature change
attachToActivity activity parameter changed to ExclusiveAppComponent instead of Activity.
These breaking change docs are accurate, as of the release under which they are published. Over time, the workarounds described here might become inaccurate. We don't, in general, keep these breaking change docs up to date as of each release.
Thebreaking change index file lists the docs created for each release.
Summary
# If you use standard Android embedding Java classes likeFlutterActivity orFlutterFragment, and don't manually embed aFlutterView inside your own customActivity (this should be uncommon), you can stop reading.
A newActivityControlSurface method:
voidattachToActivity(@NonNullExclusiveAppComponent<Activity>exclusiveActivity,@NonNullLifecyclelifecycle);is replacing the now deprecated method:
voidattachToActivity(@NonNullActivityactivity,@NonNullLifecyclelifecycle); The existing deprecated method with theActivity parameter was removed in Flutter 2.
Context
# In order for custom Activities to also supply theActivity lifecycle events Flutter plugins expect using theActivityAware interface, theFlutterEngine exposed agetActivityControlSurface() API.
This allows custom Activities to signal to the engine (with which it has a(0|1):1 relationship) that it was being attached or detached from the engine.
This lifecycle signaling is done automatically when you use the engine's bundledFlutterActivity orFlutterFragment, which should be the most common case.
However, the previous API had the flaw that it didn't enforce exclusion between activities connecting to the engine, thus enablingn:1 relationships between the activity and the engine, causing lifecycle cross-talk issues.
Description of change
# AfterIssue #21272, instead of attaching your activity to theFlutterEngine by using the:
voidattachToActivity(@NonNullActivityactivity,@NonNullLifecyclelifecycle);API, which is now deprecated, instead use:
voidattachToActivity(@NonNullExclusiveAppComponent<Activity>exclusiveActivity,@NonNullLifecyclelifecycle); AnExclusiveAppComponent<Activity> interface is now expected instead of anActivity. TheExclusiveAppComponent<Activity> provides a callback in case your exclusive activity is being replaced by another activity attaching itself to theFlutterEngine.
voiddetachFromActivity();API remains unchanged and you're still expected to call it when your custom activity is being destroyed naturally.
Migration guide
# If you have your own activity holding aFlutterView, replace calls to:
voidattachToActivity(@NonNullActivityactivity,@NonNullLifecyclelifecycle);with calls to:
voidattachToActivity(@NonNullExclusiveAppComponent<Activity>exclusiveActivity,@NonNullLifecyclelifecycle); on theActivityControlSurface that you obtained by callinggetActivityControlSurface() on theFlutterEngine.
Wrap your activity with anExclusiveAppComponent<Activity> and implement the callback method:
voiddetachFromFlutterEngine(); to handle your activity being replaced by another activity being attached to theFlutterEngine. Generally, you want to perform the same detaching operations as performed when the activity is being naturally destroyed.
Timeline
# Landed in version: 1.23.0-7.0.pre
In stable release: 2.0.0
References
#Motivating bug:Issue #66192—Non exclusive UI components attached to the FlutterEngine causes event crosstalk
Unless stated otherwise, the documentation on this site reflects Flutter 3.38.6. Page last updated on 2025-10-28.View source orreport an issue.