Add a way to supply Android manifest fragments from the Flutter SDK

[bleroux]

Use case

Some features might require the addition of a section to the Android manifest file. This is the case for #139361.

The flutter create templates can be updated to add the required section to newly created projects, but this doesn't solve the problem for existing Flutter apps.

Potentially this could be handled by writing migrations to update the AndroidManifest.xml source files in the app's tree, but (a) migrations are always tricky; (b) if for some reason a developer wanted to opt out of a given change, that approach doesn't offer a great answer for them. So this issue proposes a different solution.

Proposal

Add a way for the Flutter SDK to supply one more Android manifest source file for the Android build process to merge together when it produces the manifest for the built app.

This is something Flutter plugins already routinely do. For Flutter itself, it'd probably involve adding an AndroidManifest.xml file somewhere in the framework tree under packages/flutter_tools/, like where the Gradle build scripts appear, and then having our Gradle build scripts include that file among the sources when building the app.

For any element we add that a developer wants to opt out of, they can always tell the Android build process to leave it out by saying tools:node="remove" at a corresponding spot in their own AndroidManifest.xml source file.

Once we have that mechanism:

• We could use it for the <queries> element added in [flutter_tools] - Add queries section to Android manifest file #137207. This would cause [Android] Respect custom system-wide text selection toolbar buttons #139361 to start working for existing Flutter apps, fixing a platform-fidelity issue.
• We could use it for the INTERNET permission, which today is handled with the flutter create template: the template puts <uses-permission android:name="android.permission.INTERNET"/> in the files android/app/src/{debug,profile}/AndroidManifest.xml. Using the new mechanism, those would become redundant and the template could be simplified by removing them — so in fact both those files can be completely deleted from the template.
• There may be other pieces of AndroidManifest.xml that would also be productive to move to this mechanism instead of the flutter create templates. In general, this should be used for details that are determined by Flutter and just need to be in the manifest for the Flutter tool and engine to fully do their jobs; the templates should be used where we're just filling in a starting point for the developer to adjust from there.

(Based on the discussion starting at #139361 (comment) .)

[gnprice]

Thanks @bleroux for filing this! I revised the description and title based on the previous proposal, and expanded it a bit.

Adapting a later comment of mine (#139361 (comment)) in the linked thread: here's a couple of ways to see examples of how Flutter plugins already do the thing this issue proposes to have the Flutter SDK also do.

If you run the following command from the root of the flutter/packages repo, it'll show you all the examples in those plugins: git ls-files '*/android/src/*/AndroidManifest.xml' | xargs head -20

Here's one of them:

==> packages/local_auth/local_auth_android/android/src/main/AndroidManifest.xml <==
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
  package="io.flutter.plugins.localauth">
    <uses-permission android:name="android.permission.USE_BIOMETRIC" />
</manifest>

So that causes a line <uses-permission android:name="android.permission.USE_BIOMETRIC" /> to appear in the output manifest for an app that uses that plugin.

---

You can also take an app that you have lying around, open up its android/ subdirectory as its own project in Android Studio, open the manifest file, and look at the "Merged Manifest" view. That will show you the output manifest that ultimately goes into the app, and identify all the different manifest source files that contributed to it. For example in my app that screen looks like this (or did in January when I wrote the original comment, anyway): and those "android.*" sources in the right-hand pane are mostly Flutter plugins, including some from flutter/packages and some from elsewhere.

[gnprice]

And just to highlight the user-facing impact of this: late last year @bleroux fixed #139361, which is a platform fidelity issue on Android — Flutter's text-selection toolbar didn't offer the options supplied by other apps on the user's device, such as Google Translate.

The fix applies to new apps created after those changes, and to existing apps where the developer was watching Flutter development closely and mirrored the template change in their app. But for Flutter apps created in 2023 and earlier, the long tail of them still have the fidelity issue. That's because the fix requires a manifest element in order to work, and we don't currently have a good way to supply that except in the template. This proposal would let us fix the fidelity issue for those apps too.