- Applications that are in the background or not running can have - services that send out notifications to the user letting them know about - events of interest. Two examples are Calendar, which can send out notifications of - upcoming events, and Email, which can send out notifications when new - messages arrive. One of the user interface guidelines is that when the - user is in activity A, gets a notification for activity B and - picks that notification, when they press the BACK key, they should - go back to activity A. + Notifications and app widgets are two common ways that a user can launch + your app through something besides its main icon in Launcher. You must + take care when implementing these so that the user has a consistent experience + with the back button, not causing surprises in where they return to or the + state the application ends up in.
- The following scenario shows how the activity stack should work - when the user responds to a notification. -
- --This behavior doesn't necessarily happen by default. -
- --Notifications generally happen primarily in one of two ways: -
- -- Because of the way tasks work, if the taskAffinity of the - dedicated activity is kept as its default, then pressing the - BACK key (in step 6, above) would go to Calendar, rather - than Gmail. The reason is that, by default, all activities - in a given application have the same task - affinity. Therefore, the task affinity of the dedicated - activity matches the Calendar task, which is already running - in step 1. This means in step 4, choosing the notification - brings the existing Calendar event (in step 1) forward and - starts the dedicated activity on top of it. This is not - what you want to have happen. Setting the dedicated - activity's taskAffinity to empty string fixes this. -
-- There are other ways to handle notifications, such as bringing the - activity to the foreground, set to display specific data, such as - displaying the text message thread for the person who just sent a - new text message. + The + Handling + Notifications section of the developer guide's + Status Bar Notifications + documentation provides an overview of how to write code to correctly handle + notification. This dicussion applies equally to handling interactions with + app widgets.
diff --git a/docs/html/guide/topics/ui/notifiers/notifications.jd b/docs/html/guide/topics/ui/notifiers/notifications.jd index 71aa2fecd2d8b..33b0fecc9ed5a 100644 --- a/docs/html/guide/topics/ui/notifiers/notifications.jd +++ b/docs/html/guide/topics/ui/notifiers/notifications.jd @@ -16,6 +16,7 @@ user clicks it
A central part of the user's experience with a notification revolves around +how it interacts with the application's UI flow. You must implement +this correctly to provide a consistent user experience within your app.
+ +Two typical examples of notifications are provided by Calendar, which can send out +notifications of upcoming events, and Email, which can send out notifications +when new messages arrive. These represent the two recommended patterns for handling +notifications: either launching into an activity that is separate from the +main application, or launching an entirely new instance of the application +showing the appropriate point for the notification.
+ +The following scenario shows how the activity stack should work +in these two typical notification flows, first handling a Calendar notification: +
+ +Handling an Email notification:
+ +In an Email style of notification, the UI launched by the notification +shows the main application in a state representing that notification. +For example, when the Email application comes to the foreground from its +notification, it displays either the conversion list or a specific +conversation depending on whether there are multiple or only one new +email. To achieve this, we want to completely replace whatever current +state the application is in with a new activity stack representing the +new notification state.
+ +The following code illustrates how to show this kind of notification. Of
+most interest is the makeMessageIntentStack() method, which constructs
+an array of intents representing the app's new activity stack for this state.
+(If you are using fragments, you may need to initialize your fragment and
+app state so that pressing BACK will switch the UI back to its parent state.)
+The core of this is the {@link android.content.Intent#makeRestartActivityTask
+Intent.makeRestartActivityTask()} method, which constructs the root activity
+of the stack with the appropriate flags, such as
+{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TASK Intent.FLAG_ACTIVITY_CLEAR_TASK}.
In a Calendar style of notification, the UI launched by the notification +is a dedicated activity that is not part of the normal application flow. +For example, when the user receives a Calendar notification, choosing that +notification starts a special activity that displays a list +of upcoming calendar events — this view is available only +from the notification, not through the Calendar's normal user +interface.
+ +The code for posting this type of notification is very straight-forward; it +is like the above, but the {@link android.app.PendingIntent} is for just a single +activity, our dedicated notification activity.
+ +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/IncomingMessage.java + interstitial_notification} + +This is not enough, however. Normally Android considers all activities within
+an application to be part of that application's UI flow, so simply launching the
+activity like this can cause it to be mixed with your normal application back stack
+in undesired ways. To make it behave correctly, in the manifest declaration
+for the activity the attributes
+android:launchMode="singleInstance" and
+android:excludeFromRecents="true"
+must be set. The full activity declaration for this sample is:
Because of the use of singleInstance, you must be careful about launching
+any other activities from this one. These activities will be launched
+in their own task, and care must be taken to make sure this interacts
+well with the current state of your application's task. This is essentially
+the same as switching to the main application as described for the Email style
+notification shown before. Given the makeMessageIntentStack()
+method previously shown, handling a click here would look something like this:
If you don't want to use the singleInstance launch mode for
+this activity, an alternative approach is to use android:taskAffinity="".
+This tells Android that the activity should not be treated as part of the
+main application flow, so it will not get mixed together with that. All of the
+other issues discussed here do still apply, though this would allow you to start
+additional activities that are part of this notification task instead of switching
+to and replacing the main application task.
The {@link android.app.NotificationManager} is a system service that manages all