feat(app): Add support for toggling Android back button handling

[theproducer]

Adds a new configuration and runtime toggle for toggling on and off the App plugin's Android back button handling.

Disabling back button handling allows things like Android 13+ predictive back gesture to work.

closes: ionic-team/capacitor#6293

[github-actions]

Released dev build of app with dev version: 7.0.3-dev-2390-20250902T150300.0

[jcesarmobile]

Instead of adding the this.onbackPressedCallback = callback; new line, set it on the callback creation changing OnBackPressedCallback callback = new OnBackPressedCallback(true) to this.onbackPressedCallback = new OnBackPressedCallback(true) (will also need to replace other usages of callback to this.onbackPressedCallback`

While this is supposed to enable the predictive back on Android 15+, this disables the back button handling for all Android versions, so I think that should be documented as for the current comment, it appears to only have an effect on Android 15+, but it affects all Android versions.

I don't fully understand what the "predictive back" is supposed to do, I see no difference on enabling it or disabling it, other than the back button handling not being into effect, which leads to the app being minimized instead of navigating back.

[jcesarmobile]

Also, I think this should be configurable from the capacitor config file to disable it from the beginning if desired, and the name should probably be about disabling back button handling as this is what the PR really does, which is required for predictive back to work, but you are disabling the back button handling in the end and people might want to use the app plugin just for the app information and not for the back button handling.

[theproducer]

Also, I think this should be configurable from the capacitor config file to disable it from the beginning if desired, and the name should probably be about disabling back button handling as this is what the PR really does, which is required for predictive back to work, but you are disabling the back button handling in the end and people might want to use the app plugin just for the app information and not for the back button handling.

I think you are right, especially the part about people may not wanting the back button handling from the plugin at all.

I'll make those changes, and I'll keep the toggle as well (renaming it to be more generic) in case there are scenarios where devs want to temporarily enable / disable back button handling based on the state / routing of their app.

[jcesarmobile]

The new configuration is not documented, you can add this to the README to get it generated automatically

## Configuration

<docgen-config>
</docgen-config>

or you can add it manually if the generation causes issues

[jcesarmobile]

it should go over @capacitor/core, if not it will be moved automatically in the future if some dependency gets installed or uninstalled

[xEverth]

Hello Ionic Team!
Is this the place to ask for clarifications on the Hardware Back Button on an Ionic application?

The Ionic v8 documentation for Angular invites to use Platform.backButton.subscribe / subscribeWithPriority for the back button events on Android and that it's necessary to install this plugin @capacitor/app in order to have support for hardware back button in a Capacitor native app:
https://ionicframework.com/docs/developing/hardware-back-button

In my application however I find that those events are not fired, and I need to subscribe to backButton events using App.addListener('backButton'), which does not have the same priority-based handling.

If I set disableBackButtonHandler option introduced in this PR (and available since @capacitor/app@^7.1.0) to true in capacitor config, the aforementioned App listener does not fire anymore, but neither does the one in the Ionic documentation and instead the app is exited directly (even if I navigated to different pages in-app, using the Angular router).

Before I set up a sample app for reproduction, may I ask you what is the expected behavior? Should the two APIs (Ionic's and Capacitor/App) be able to used independently or does the latter disable the former?

Thank you