Android ActivityControlSurface attachToActivity signature change

目录

Summary

If you use standard Android embedding Java classes like FlutterActivity, FlutterFragment, and don’t manually embed a FlutterView inside your own custom Activity (this should be uncommon), you can stop reading.

A new ActivityControlSurface method:

void attachToActivity(
    @NonNull ExclusiveAppComponent<Activity> exclusiveActivity,
    @NonNull Lifecycle lifecycle);

is replacing the now deprecated method:

void attachToActivity(@NonNull Activity activity, @NonNull Lifecycle lifecycle);

The existing deprecated method with the Activity parameter will be removed after 2021-03-01.

Context

In order for custom Activities to also supply the Activity lifecycle events Flutter plugins expect using the ActivityAware interface, the FlutterEngine exposed a getActivityControlSurface() API.

This let custom Activities signal to the engine (with which it has a (0|1):1 relationship) that it was being attached or detached from the engine.

However, the previous API had the flaw that it didn’t enforce exclusion between activities connecting to the engine, thus enabling n:1 relationships between the activity and the engine, causing lifecycle cross-talk issues.

Description of change

After Issue #21272, instead of attaching your activity to the FlutterEngine by using the:

void attachToActivity(@NonNull Activity activity, @NonNull Lifecycle lifecycle);

API, which is now deprecated, instead use:

void attachToActivity(
    @NonNull ExclusiveAppComponent<Activity> exclusiveActivity,
    @NonNull Lifecycle lifecycle);

An ExclusiveAppComponent<Activity> interface is now expected instead of an Activity. The ExclusiveAppComponent<Activity> provides a callback in case your exclusive activity is being replaced by another activity attaching itself to the FlutterEngine.

The

void detachFromActivity();

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 a FlutterView, replace calls to:

void attachToActivity(@NonNull Activity activity, @NonNull Lifecycle lifecycle);

with calls to:

void attachToActivity(
    @NonNull ExclusiveAppComponent<Activity> exclusiveActivity,
    @NonNull Lifecycle lifecycle);

on the ActivityControlSurface that you obtained by calling getActivityControlSurface() on the FlutterEngine.

Wrap your activity with an ExclusiveAppComponent<Activity> and implement the callback method:

void detachFromFlutterEngine();

to handle your activity being replaced by another activity being attached to the FlutterEngine. 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: not yet

References

Motivating bug: Issue #66192—Non exclusive UI components attached to the FlutterEngine causes event crosstalk