[quick_actions_android] Update instructions for using a launcher acti…

…vity with more breadcrumbs (#7716)

Builds on #7686 to give more context about the issue I solved in flutter/flutter#152883 and hopefully leave better breadcrumbs for developers that find themselves wanting to use a launcher activity and the `quick_actions_android` plugin.

Fixes flutter/flutter#152883.

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.

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

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