Develop Reference

Behavior of FLAG_ACTIVITY_NEW_TASK | FLAG_ACTIVITY_MULTIPLE_TASK

As per the documentation of FLAG_ACTIVITY_MULTIPLE_TASK:
This flag is used to create a new task and launch an activity into it.
This flag is always paired with either FLAG_ACTIVITY_NEW_DOCUMENT or FLAG_ACTIVITY_NEW_TASK. In both cases these flags alone would search through existing tasks for ones matching this Intent.This flag is ignored if one of FLAG_ACTIVITY_NEW_TASK or FLAG_ACTIVITY_NEW_DOCUMENT is not also set.
When paired with FLAG_ACTIVITY_MULTIPLE_TASK both of these behaviours are modified to skip the search for a matching task and unconditionally start a new task. When used with FLAG_ACTIVITY_NEW_TASK, a new task is always started to host the Activity for the Intent, regardless of whether there is already an existing task running the same thing.
Because the default system does not include graphical task management, you should not use this flag unless you provide some way for a user to return back to the tasks you have launched. See FLAG_ACTIVITY_NEW_DOCUMENT for details of this flag's use for creating new document tasks.
So this means that if I have an activity 1 which opens activity 2 with both of these flags, the 2 activities are opened in different stacks and are thus available as different tasks in recent.
However my question is to understand the behaviour of back button in this scenario.
ideally when activities are launched without any flags, pressing back on them destroys the activity and it is removed from the backstack. if there are no activities, the system exits the app but keeps the backstack with the last activity.
however in this case when i press back, 2 different beaviors are observed:
(Scenario: An app that launches Activity1 which launches Activity2 which launches Activity3 via startActivity(Intent(...).also{it.flags = FLAG_ACTIVITY_NEW_TASK or FLAG_ACTIVITY_MULTIPLE_TASK}) )
if i just press back on Activity 3 , i move to Activity 2 . similarly when i press back on Activity 2, i move to Activity 1. and finally when i press back on Activity 1, i exit the app . however, i can see all the activities remain in recents and available to be opened. when i open any of them and press back, then this time, i just get exited from the app into homescreen. video sample
if i press recents on any of the activities while traversing forward, the back-press stops working, and instead i get exited from any of the activity in recents. video sample
So :
why is this behaviour?
Can we assume that if there is just 1 activity in a back-stack, it will show up in recents and not get destroyed, unless the user explicitly clears it from the recents?
Why Activities show a weak link to the caller activity in 1st case and going back to the parent back-stack when press back in 1st scenario?

How to replicates examples in the Android Tasks and Backstack documentation?

I'm trying to understand the Android Tasks and Back stack by reading the official documentation: https://developer.android.com/guide/components/activities/tasks-and-back-stack
I have a couple of questions regarding the documentation.
Question 1: In Figure 4. in the documentation, there are 2 tasks - a foreground and a background task, the background tasks contains Activity Y and X, if the Activity Y is declared with a singleTask launch mode, how is it possible to create a task with activity Y on top of activity X?
For other questions, I prepared a simple project - 2 activities, A and B. On both activities I have 2 buttons:
Button A opens Activity A
Button B opens Activity B
Activity A is the MAIN (LAUNCHER) activity.
Question 2: The documentation says that using the intent flag FLAG_ACTIVITY_NEW_TASK produces the same behavior as using the singleTask launcher mode:
This produces the same behavior as the "singleTask" launchMode value, discussed in the previous section.
This is not what I see from my test application. If the activity B has a launcher mode set to singleTask and if my backstack is A -> B -> A -> A, then if I open B the back stack will look like A -> B (it will pop the last 2 As). I guess that the reason behind it is the tasks created: when the launcher intent was sent it opened the activity A in the new task (let's call it to task 1), when I opened B, it opened it in task 2 (because it has a singleTask launch mode), then the 2 A activities where opened in Task 2 as well. After opening B again, Android found a task that already has a B activity (Task 2) and it brought it to the front, poping 2 As.
However, using a FLAG_ACTIVITY_NEW_TASK instead of singleTask does not produce the same behavior, it just opens B on top of everything else. Is the documentation wrong, or am I doing something wrong?
Question 3: The example at the end says:
the two launch modes that mark activities as always initiating a task, "singleTask" and "singleInstance", should be used only when the activity has an ACTION_MAIN and a CATEGORY_LAUNCHER filter. Imagine, for example, what could happen if the filter is missing: An intent launches a "singleTask" activity, initiating a new task, and the user spends some time working in that task. The user then presses the Home button. The task is now sent to the background and is not visible. Now the user has no way to return to the task, because it is not represented in the app launcher.
How to reproduce that? In my previous example, I open the activity B in a new task, but if I hit the home button and the launcher icon again, I get back to activity B. So even though I'm using a singleTask launcher mode, I'm still able to return to that task by using the launcher icon or selecting it from the list of the recent applications.
It's entirely possible that I'm doing something wrong here and that new tasks are not generated, is there a way to see all tasks and activities for a specific application?
Thanks.

Today I spent more time trying to understand what's going on here and I think I have the answers. I realized that nothing in my example created new tasks. Tasks are visible in the Recent screens (apps in the background) - at least on Android 5+.
So, the first question that should be answered is: Why creating activity B is not creating a new task?
It's because generating new tasks goes hand in hand with the taskAffinity property. If you don't specify this property, your activity will have the default taskAffinity which is your application's package name. When you open the activity with a singleTask launcher mode, Android will look for tasks with the same affinity (task's affinity is defined by its root activity affinity) and if it finds one it will add your activity to that task. Because I didn't specify the affinity, android assumed I want to add my activity to the task with an affinity equal to the application's package and it didn't create new tasks at all. It just added an activity to an existing task.
That being said, FLAG_ACTIVITY_NEW_TASK and singleTask are very much different, although sometimes they produce the same behavior. If you trigger an intent with the FLAG_ACTIVITY_NEW_TASK flag that is trying to open an activity A without specifying activity's taskAffinity you'll just normally add an activity on top of the current task. (This is still confusing to me, I would expect it to open an activity only if the activity is not in the stack; if it is, it should do nothing.)
Opening the same activity without this flag but using the singleTask mode, will again not create a new task but will:
Add the activity on top if it's not in the stack (this is the answer to question 1)
Destroy all activities on top of yours and call onNewIntent if the activity is already in the stack. (I think that branch.io uses this method to handle deep links - which seems really hacky to me, but...)
On the other hand, if you specify the taskAffinity for your activity then:
if singleTask mode is set, android will search for the task with this affinity and if it's present it will
add your activity on top if the activity is not on task's backstack
destroy all activities on top of your activity and call onNewIntent if the activity is in the back stack.
If the task is not present, it will create a new one and add your activity as root.
if FLAG_ACTIVITY_NEW_TASK flag is set in the intent, android will search for the task with the specified affinity and if it finds one it will just bring that task to the foreground, without destroying the stack or calling onNewIntent. (I tested that if the activity is in the back stack, I guess that if the activity is not in the back stack it would push it to the task's stack).
So, to answer question 2. The flag FLAG_ACTIVITY_NEW_TASK and the launcher mode singleTask are different. I guess that similar behavior can be achieved by using 2 more flags FLAG_ACTIVITY_CLEAR_TOP and FLAG_ACTIVITY_SINGLE_TOP.
I think that the example in the documentation regarding question 3 is relevant for older versions of Android (lower than 5.0). There different tasks were not shown in the Recent Screens - here's the documentation: https://developer.android.com/guide/components/activities/recents.

Remove app completely from memory on exit

I am building an Android app, which starts a service that keeps running in the background. When the user uses the Home button to close one of the activities (which communicate with the service), and then navigates to the app again, they get the last activity. This is correct behaviour.
However, when I explicitly stop the service (via an option in the menu), the app should "Quit". Currently, that works like this:
stopService(new Intent(this, MyService.class));
finish();
// just go to to the home screen, as it is intended in Android
Intent intent = new Intent(Intent.ACTION_MAIN);
intent.addCategory(Intent.CATEGORY_HOME);
intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
startActivity(intent);
and that works fine. But when I now navigate to the app again, it starts the previously opened Activity. What I want is that it starts the starting activity again (the launcher).
How could I accomplish that?

System.exit(0);
But you should have only one Activity in stack.

If you look at the description of android:excludeFromRecents it says:
Whether or not the task initiated by this activity should be excluded from the list of recently used applications ("recent apps").
isn't this what you are looking for ? Once the user hits exit, this app won't be in the recently used apps and hence will be completely removed from memory ? :)

I think that removing 'the app completely from memory on exit' is not the issue. Even if you stop your service the process is likely to remain in memory - that is the systems' decision.
You want an explicit, custom behaviour - user chooses your 'exit' option from menu --> next app launch starts at main activity - so you will need to handle this explicitly.
The default behaviour is that the user returns to their last activity when they re-launch. So they only return to the main activity if they exit by 'backing out' through your activities. Your use of an 'exit' menu option is non-standard (not to say it is bad).
One option would be to do the backing out through your activities yourself. Perhaps now you are just finishing the current activity and you should instead finish all the activities in the back stack.
Another option is that you could save a flag, and when the UI is launched again you could read that flag and launch the appropriate activity (but again be careful with the backstack). The easiest way to set that flag is probably by overriding onSaveInstanceState(Bundle) and then reading the bundle in onCreate (or use sharedpreferences).

Have you tried setting the clearTaskOnLaunch to true for your main activity (in your manifest).
From the documentation:
When the value is "true", every time users start the task again, they are brought to its root activity regardless of what they were last doing in the task and regardless of whether they used the Back or Home button to leave it.
This seems to describe what you want to do. I have never tried this personally, but it seems worth investigating for your purpose.

How to launch activity the same way launchers do?

I have an Activity A which is declared as singleTop and android.intent.action.MAIN in Android Manifest. I start it from launcher, then launch another activity B through Intent and then press Home button. Now I have a task with activity stack "A, B" waiting in background. If I then again start activity A from launcher I get back already running instance with a stack restored (activity B running in foreground).
This is nice. And I want to achieve the same effect when launching activity A from my own Notification. I've tried different combinations of Intent flags but I've got either a new instance of activity A or the same instance but with cleared stack (no activity B in foreground).

First of all, let's make sure that the system won't kill your Activity B when you are not using that task for a long time.
If the user leaves a task for a long time, the system clears the task of all activities except the root activity. When the user returns to the task again, only the root activity is restored. The system behaves this way, because, after an extended amount of time, users likely have abandoned what they were doing before and are returning to the task to begin something new.
There are some activity attributes that you can use to modify this behavior:
alwaysRetainTaskState: If this attribute is set to "true" in the root activity of a task, the default behavior just described does not happen. The task retains all activities in its stack even after a long period. So what you need to do is to set this to true under your <activity> tag in your manifest file for A.
Second, you won't need singleTop. Check this figure from Android docs. I guess this is what you want. If you start an activity that specifies the singleTask launch mode, then if an instance of that activity exists in a background task, that whole task is brought to the foreground. At this point, the back stack now includes all activities from the task brought forward, at the top of the stack.
So you also need to add singleTask under the tag of A and B, instead of singleTop. Then, you need to launch activity A from Notification without any flags but FLAG_ACTIVITY_NEW_TASK and FLAG_ACTIVITY_REORDER_TO_FRONT(optional).
I haven't tried this myself but I have a strong belief that it will work. Try it and let me know if it doesn't.

launch external activity w/o it appearing in the back stack

I need to launch an external activity (which isn't mine) for a split second, and then I have a service that launches my previous activity for the user to see.
This works great, but the problem is when the user then presses the back key, he gets to that external activity.
I have two different activity launches here, one for the external activity, and one for my activity to return to (in which I need to use FLAG_ACTIVITY_NEW_TASK because I'm launching it from a service).
For these two launches I've tried any combination of:
FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET, FLAG_ACTIVITY_NO_HISTORY, FLAG_ACTIVITY_NEW_TASK, FLAG_ACTIVITY_CLEAR_TOP, FLAG_ACTIVITY_CLEAR_TASK, FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS.
Nothing helps, I keep seeing the external activity after pressing back.
I've seen some similar questions here, but they all have the middle activity in their own app, so they can call finish on it, or set noHistory="true" in the manifest.
Any ideas?
UPDATE:
Seems like the issue is that I re-launch my previous activity from a service, which means I need to give it FLAG_ACTIVITY_NEW_TASK, from the documentation of Tasks and Back Stack:
FLAG_ACTIVITY_NEW_TASK Start the activity in a new task. If a task is
already running for the activity you are now starting, that task is
brought to the foreground with its last state restored and the
activity receives the new intent in onNewIntent(). This produces the
same behavior as the "singleTask" launchMode value, discussed in the
previous section.
And from the singleTask paragraph:
"singleTask" The system creates a new task and instantiates the activity at the root of the new task
...
Note: Although the activity starts in a
new task, the Back button still returns the user to the previous
activity.
So I need a flag that overrides this behavior somehow...