Determine lifecycle by looking at window focus also

[gspencergoog]

Description

This incorporates additional signal from Activity.onWindowFocusChanged to help decide if the application is resumed or inactive.

When the user pulls down the notification shade or opens the app switcher in iOS, then iOS sends a notification to the application that it no longer has input focus (is no longer "active" in Apple terminology).

However, Android (at least on a Pixel) doesn't send onPause and onResume events for these things, as one might expect. Instead, this PR changes things so that we listen to Activity.onWindowFocusChanged and see if any of the windows still have focus.

If it doesn't have focus, then the lifecycle switches to inactive (even if onPause hasn't been called), and if it does have focus (and onResume hasn't been called) then we should go to resumed.

State changes are determined and deduped in the LifecycleChannel class.

Here's the old state table:

Android State	Flutter state
Resumed	resumed
Paused	inactive
Stopped	paused
Detached	detached

Here's the new state table:

Android State	Window focused	Flutter state
Resumed	true	resumed
Resumed	false	inactive *
Paused	true	inactive
Paused	false	inactive
Stopped	true	paused
Stopped	false	paused
Detached	true	detached
Detached	false	detached

• = This is the relevant change in this PR.

("Window focused" means one or more windows managed by Flutter are focused)

The inactive state is for when the application is running and visible, but doesn't have the input focus. An example where this currently happens are when a phone call is in progress on top of the app, or on some OEMs when going into the app switcher (I've tested on Realme and it does that, at least). With the PR, it will also go into inactive when the app has lost input focus, but is still in the Android onResume state. This means that on phones that don't pause the app when they go into the app switcher or the notification window shade (Pixel, others), the app will go into inactive when it didn't before. If developers weren't doing anything special in the inactive state before, then this PR will have no change for them. If they were, they will go into that state more often (but more consistently across OEMs).

Related Issues

• Fixes didChangeAppLifecycleState - different behaviour iOS vs Android flutter#124591

Tests

• Added unit tests for handling onWindowFocusChanged.

[reidbaker]

This code looks great but it will need some tests. Specifically tests to make sure that we are forwarding the onWindowFocusChanged events. I pinged another contributor for a second opinion about the potential risks of having a second item set inactive.

My final thought is about ensuring that android activities forward the onWindowFocusChanged call along to flutter fragments. Do you know if we have the ability to write custom linters to warn the caller if they dont forward events to us?

[gnprice]

Seems good to me. Comments below.

• That the onWindowFocusChanged will report false, even when one of the windows in the activity is focused (I'm not sure yet what it does when you switch between one window and another in a multi-window app).

Yeah, I'd expect that if you have two activities visible in multi-window mode and you switch focus from one to the other, then the system would call onWindowFocusChanged(false) on the one activity and onWindowFocusChanged(true) on the other.

That should be pretty similar to what happens if you switch between activities in the app switcher, which I believe will call onStop on one activity and onResume et al. on the other. So if that causes confusion in Flutter, then it's probably a confusion that already exists.

[gspencergoog]

I removed the state in the LifecycleChannel (the private String lastState variable), since I think it's too easy to get out of sync with the real state of the Android Activity, or with the state in the framework, since an add-to-app activity could start handling the lifecycle states, or could send messages to the framework to change the state on its own. Sure, not common things, but they could happen.

Sending extra state updates in the case where we move from inactive to resumed or vice versa are unfortunate, but I'd rather have one source of truth for the state of the app and just deduplicate them.

Off to writing tests now.

[gspencergoog]

Specifically tests to make sure that we are forwarding the onWindowFocusChanged events. I pinged another contributor for a second opinion about the potential risks of having a second item set inactive.

What should those tests look like? I've added a unit test to verify that we do the right thing when we receive onWindowFocusChanged, but I don't know how to write something to test that a fragment receives the events when we also handle them. Are there already tests like these for fragments that I could look at as an example?

Do you know if we have the ability to write custom linters to warn the caller if they don't forward events to us?

No, I don' t know the answer to that, maybe @gnprice knows?

[xster]

not sure the or is apt here. If you consider the first part of the or, 'an app having focus while in Android's "resumed" state' could be true most of the time while this enum isn't resumed in hybrid apps

[math1man]

It's also worth noting that "focus" here refers to the window, and a single application may have more than one window, thus implying part of the application has focus while other parts don't. I think even something as simple as displaying a native Android dialog (which a plugin could do) would trigger onWindowFocusChanged.

[gspencergoog]

What are the possible values it could be set to in the hybrid case where the app has focus and is in the Android resumed state?

I am assuming that if "onResume" has been called by Android on the activity, and the Flutter activity has focus, then the only Flutter state this should be in is "resumed". If the Flutter activity doesn't have focus, then it should be in "inactive".

[xster]

I'm picking on the doc wording, not on the implementation. It's not "the app OR the Flutter host view having focus", it's just "the Flutter host view having focus". In hybrid apps where 95% of the app isn't Flutter, you're not going to be AppLifecycleState.resumed if "the app has focused while in Android's resumed state". The Flutter view might not even be attached to the FlutterEngine

[gspencergoog]

I'm picking on the doc wording, not on the implementation.

Sure, I got that, and a totally fine thing to do! I want to get it right.

In hybrid apps where 95% of the app isn't Flutter, you're not going to be AppLifecycleState.resumed if "the app has focused while in Android's resumed state". The Flutter view might not even be attached to the FlutterEngine.

If the Flutter view isn't attached to the engine, wouldn't it be in Android's "Detached" state? In that state, it doesn't matter what the focus is, the Flutter state will be AppLifecycleState.detached. Only in Android's "Resumed" state am I making any changes to how things work. Take a look at the state table I put in the PR description and tell me if that helps explain it.

[gspencergoog]

Okay, I've updated it so that LifecycleChannel keeps track of the focus state and emits the appropriate state to the framework for the combination of Android lifecycle state and focus state.

[gnprice]

I like this state-table-based approach!

[gspencergoog]

Okay, I've added tests for the LifecycleChannel, and I've done manual testing on some devices. Are there any other tests I should add?

Otherwise, I think this is ready for another look.

[math1man]

Overall LGTM

[reidbaker]

Great documentation!