[Android] Add predictive back support for FlutterFragment and FlutterFragmentActivity

[moko256]

This PR will wire FlutterFragment up to BackGestureChannel via FlutterActivityAndFragmentDelegate.

When shouldAutomaticallyHandleOnBackPressed is set to true, FlutterFragment will handle back gesture events.
Since FlutterFragmentActivity uses FlutterFragment with this property enabled, it will also handle these events as a result of this PR.

Fixes: #149753

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
• I signed the CLA.
• I listed at least one issue that this PR fixes in the description above.
• I updated/added relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or this PR is test-exempt.
• I followed the breaking change policy and added Data Driven Fixes where supported.
• All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

[gemini-code-assist]

Code Review

This pull request adds support for predictive back gestures in FlutterFragment and FlutterFragmentActivity on Android 14 (API 34) and higher. The implementation correctly uses an SDK version check to provide different OnBackPressedCallback implementations. For API 34+, it handles the new back gesture events (start, progress, commit, cancel) and delegates them to FlutterActivityAndFragmentDelegate. For older versions, it maintains the existing onBackPressed behavior. The changes are accompanied by new Robolectric tests that verify the behavior on both SDK 33 and SDK 34, ensuring the new logic is correctly triggered. The code is well-structured and the changes are solid. I have one minor suggestion to improve test code maintainability.

[gemini-code-assist]

This block of verification logic is very similar to the one on lines 390-393. To improve readability and reduce code duplication, consider extracting this logic into a private helper method.

For example, you could create a method like this:

private void verifyBackGestureCalls(FlutterActivityAndFragmentDelegate mockDelegate, org.mockito.verification.VerificationMode mode) {
  verify(mockDelegate, mode).startBackGesture(any());
  verify(mockDelegate, mode).updateBackGestureProgress(any());
  verify(mockDelegate, mode).commitBackGesture();
  verify(mockDelegate, mode).cancelBackGesture();
}

Then you could call it with times(0) and times(1) respectively.

[moko256]

FlutterFragmentActivity:

Screen_recording_20260119_005512.webm

FlutterFragment with another Fragment:

Screen_recording_20260119_005806.webm

Code that I used to check behavior

main.dart:

import 'package:flutter/material.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(primarySwatch: Colors.blue),
      home: const MainScreen(),
    );
  }
}

class MainScreen extends StatelessWidget {
  const MainScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text("Main")),
      body: Center(
        child: ElevatedButton(
          onPressed: () {
            Navigator.push(
              context,
              MaterialPageRoute(builder: (context) => DetailScreen()),
            );
          },
          child: Text('See details'),
        ),
      ),
    );
  }
}

class DetailScreen extends StatelessWidget {
  const DetailScreen({super.key});

  @override
  Widget build(BuildContext context) {
    final message = "Details";

    return Scaffold(
      appBar: AppBar(title: Text(message)),
      body: Center(child: Text(message)),
    );
  }
}

MainActivity.kt:

class MainActivity : FlutterFragmentActivity()

class MainActivity : FragmentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        supportFragmentManager.beginTransaction()
            .add(android.R.id.content, InitialFragment())
            .commit()
    }

    class InitialFragment : Fragment() {
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
        }

        @SuppressLint("SetTextI18n")
        override fun onCreateView(
            inflater: LayoutInflater,
            container: ViewGroup?,
            savedInstanceState: Bundle?
        ): View {
            val button = Button(activity)
            button.text = "Go Flutter"
            button.setOnClickListener {
                val activity = activity ?: return@setOnClickListener

                val flutterFragment = FlutterFragment.NewEngineFragmentBuilder()
                    .shouldAutomaticallyHandleOnBackPressed(true)
                    .build<FlutterFragment>()

                activity.supportFragmentManager.beginTransaction()
                    .add(android.R.id.content, flutterFragment)
                    .addToBackStack("Flutter")
                    .commit()
            }
            return button
        }
    }
}

[justinmc]

@moko256 Thank you so much for contributing this! I've been hoping we'd add support here for a long time but we never got the time to do it.

I'll defer to @gmackall for final approval but this looks good to me 👍

[gmackall]

Thanks!

[auto-submit]

autosubmit label was removed for flutter/flutter/181124, because The base commit of the PR is older than 7 days and can not be merged. Please merge the latest changes from the main into this branch and resubmit the PR.

[moko256]

@justinmc @gmackall I'm not sure why the Google test failed. Since I'm an external contributor, I don't have access to the test logs. Could you please take a look?

[reidbaker]

@moko256 thank you for your contribution. I am investigating the internal failure and should have an answer for you today. Right now I believe there is nothing you need to do on your side.

[reidbaker]

Google3 testing failure is overridden by me. Thank you again for your contribution!