From a566da6a0f88db56890b61a17d3705b8188e7d0c Mon Sep 17 00:00:00 2001 From: Camille Simon <43054281+camsim99@users.noreply.github.com> Date: Wed, 2 Oct 2024 17:33:03 +0100 Subject: [PATCH] [quick_actions_android] Update instructions for using a launcher activity with more breadcrumbs (#7716) Builds on https://github.com/flutter/packages/pull/7686 to give more context about the issue I solved in https://github.com/flutter/flutter/issues/152883 and hopefully leave better breadcrumbs for developers that find themselves wanting to use a launcher activity and the `quick_actions_android` plugin. Fixes https://github.com/flutter/flutter/issues/152883. --- .../quick_actions_android/CHANGELOG.md | 5 ++ .../quick_actions_android/README.md | 69 +++++++++++++++---- .../quick_actions_android/pubspec.yaml | 2 +- 3 files changed, 61 insertions(+), 15 deletions(-) diff --git a/packages/quick_actions/quick_actions_android/CHANGELOG.md b/packages/quick_actions/quick_actions_android/CHANGELOG.md index 37c75366b57f..3350b35e862c 100644 --- a/packages/quick_actions/quick_actions_android/CHANGELOG.md +++ b/packages/quick_actions/quick_actions_android/CHANGELOG.md @@ -1,3 +1,8 @@ +## 1.0.17 + +* Updates README to include more specific context on how to use launcher activities, including + a full explanation for https://github.com/flutter/flutter/issues/152883. + ## 1.0.16 * Updates README to include guidance on using the plugin with a launcher activity. diff --git a/packages/quick_actions/quick_actions_android/README.md b/packages/quick_actions/quick_actions_android/README.md index 5c7be83e8a16..a952e3840adf 100644 --- a/packages/quick_actions/quick_actions_android/README.md +++ b/packages/quick_actions/quick_actions_android/README.md @@ -13,17 +13,27 @@ should add it to your `pubspec.yaml` as usual. ## Usage with launcher activities -If your app implements an activity that launches the main `FlutterActivity` -(`MainActivity.java`/`MainActivity.kt` by default), then you may need to change -the launch mode of your launcher activity and/or modify the `Intent` flags used -to launch the main `FlutterActivity` in order to achieve the desired back press -behavior and task management. - -If your launcher activity only launches the main `FlutterActivity` without any -additional relevant logic (like the code sample provided in the description of -https://github.com/flutter/flutter/issues/152883), to have your app maintain the -same behavior of `quick_actions_android` with/without a launcher activity, set -the launch mode of your launcher activity to `singleInstance` in +If you have an activity that launches a `FlutterActivity` (this is +`MainActivity.java`/`MainActivity.kt` by default), then you might need to +modify the launch configuration of that activity to have the back press +behavior and task back stack that you expect. Common use cases of having +such a launcher activity are in an add to app project or if your Flutter +project contains multiple Android activities. + +For example, consider the case where you have two different quick actions +shortcuts for your app and a launcher activity that launches the +`FlutterActivity`. If the launcher activity uses the [`singleTop`][4] launch +mode (as Flutter's default `MainActivity.java`/`MainActivity.kt` do by default) +and the user + +1. Launches your app from the first shortcut +2. Moves your app into the background by exiting the app +3. Re-launches your app from the second shortcut + +then the user will see what the first shortcut launched, not what the second +shortcut was supposed to launch. To fix this, you may set the launch mode of +the launcher activity to `singleInstance` (see [Android documentation][5] for +more information on this mode) in `your_app/android/app/src/mainAndroidManifest.xml`: ```xml @@ -32,8 +42,37 @@ the launch mode of your launcher activity to `singleInstance` in android:launchMode="singleInstance"> ``` -See the [Tasks and the back stack][4] Android documentation for more information -on the different launch modes and `Intent` flags you may need. +See [this issue][6] for more context on this exact scenario and its solution. + +Depending on your use case, you may additionally need to set the proper launch +mode `Intent` flags in the `Intent` that launches the `FlutterActivity` to +achieve your expected back press behavior and task back stack. For example, +if `MainActivity.java` is the `FlutterActivity` that your launcher activity +launches: + +```java +public final class LauncherActivity extends Activity { + + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + + Intent mainActivityIntent = new Intent(this, MainActivity.class); + mainActivityIntent.putExtras(getIntent()); + + // Add any additional launch mode Intent flags you need: + mainActivityIntent.addFlags(...); + + startActivity(mainActivityIntent); + finish(); + } + + ... +} +``` + +See [Tasks and the back stack][5] for more documentation about the different +launch modes and related `Intent` flags that Android provides. ## Contributing @@ -42,4 +81,6 @@ If you would like to contribute to the plugin, check out our [contribution guide [1]: https://pub.dev/packages/quick_actions [2]: https://flutter.dev/to/endorsed-federated-plugin [3]: https://github.com/flutter/packages/blob/main/CONTRIBUTING.md -[4]: https://developer.android.com/guide/components/activities/tasks-and-back-stack#TaskLaunchModes +[4]: https://developer.android.com/reference/android/content/Intent?authuser=1#FLAG_ACTIVITY_SINGLE_TOP +[5]: https://developer.android.com/guide/components/activities/tasks-and-back-stack#TaskLaunchModes +[6]: https://github.com/flutter/flutter/issues/152883#issuecomment-2305906933 diff --git a/packages/quick_actions/quick_actions_android/pubspec.yaml b/packages/quick_actions/quick_actions_android/pubspec.yaml index 9f2dd2f70987..794c5f830823 100644 --- a/packages/quick_actions/quick_actions_android/pubspec.yaml +++ b/packages/quick_actions/quick_actions_android/pubspec.yaml @@ -2,7 +2,7 @@ name: quick_actions_android description: An implementation for the Android platform of the Flutter `quick_actions` plugin. repository: https://github.com/flutter/packages/tree/main/packages/quick_actions/quick_actions_android issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+in_app_purchase%22 -version: 1.0.16 +version: 1.0.17 environment: sdk: ^3.4.0