In this document
-
-
- Notification Display Elements
-
-
-
- Normal view -
- Big view -
+ - Design Considerations
- Creating a Notification
- Required notification contents @@ -18,7 +13,7 @@ page.title=Notifications
- Notification actions
- Notification priority
- Creating a simple notification -
- Applying a big view style to a notification +
- Applying an expanded layout to a notification
- Handling compatibility
@@ -40,6 +35,13 @@ page.title=Notifications
- Displaying a continuing activity indicator
+ src="{@docRoot}images/ui/notifications/notification_area.png"
+ height="" alt="" />
Figure 1. Notifications in the notification area.
-
+
Figure 2. Notifications in the notification drawer.
-- Notification Design -
-- Notifications, as an important part of the Android UI, have their own design guidelines. To - learn how to design notifications and their interactions, read the Android Design Guide - Notifications topic. -
-- Note: Except where noted, this guide refers to the - {@link android.support.v4.app.NotificationCompat.Builder NotificationCompat.Builder} class - in the version 4 Support Library. - The class {@link android.app.Notification.Builder Notification.Builder} was added in Android - 3.0. -
- - -Notification Display Elements
-- Notifications in the notification drawer can appear in one of two visual styles, depending on - the version and the state of the drawer: -
--
-
- - Normal view - -
- - The standard view of the notifications in the notification drawer. - -
- - Big view - -
- - A large view that's visible when the notification is expanded. Big view is part of the - expanded notification feature available as of Android 4.1. - -
- These styles are described in the following sections. -
- -Normal view
-- A notification in normal view appears in an area that's up to 64 dp tall. Even if you create a - notification with a big view style, it will appear in normal view until it's expanded. This - is an example of a normal view: -
-
-- Figure 3. Notification in normal view. -
-- The callouts in the illustration refer to the following: -
--
-
- Content title -
- Large icon -
- Content text -
- Content info -
- Small icon -
- - Time that the notification was issued. You can set an explicit value with - {@link android.support.v4.app.NotificationCompat.Builder#setWhen setWhen()}; if you don't - it defaults to the time that the system received the notification. - -
Big view
-- A notification's big view appears only when the notification is expanded, which happens when the - notification is at the top of the notification drawer, or when the user expands the - notification with a gesture. Expanded notifications are available starting with Android 4.1. -
-- The following screenshot shows an inbox-style notification: -
-
-- Figure 4. Big view notification. -
-- Notice that the big view shares most of its visual elements with the normal view. The - only difference is callout number 7, the details area. Each big view style sets this area in - a different way. The available styles are: -
--
-
- - Big picture style - -
- - The details area contains a bitmap up to 256 dp tall in its detail section. - -
- - Big text style - -
- - Displays a large text block in the details section. - -
- - Inbox style - -
- - Displays lines of text in the details section. - -
- All of the big view styles also have the following content options that aren't - available in normal view: -
--
-
- - Big content title - -
- - Allows you to override the normal view's content title with a title that appears only in - the expanded view. - -
- - Summary text - -
- - Allows you to add a line of text below the details area. - -
- Applying a big view style to a notification is described in the section - Applying a big view style to a notification. -
- - + +Note: Except where noted, this guide refers to the +{@link android.support.v4.app.NotificationCompat.Builder NotificationCompat.Builder} class +in the version 4 Support Library. +The class {@link android.app.Notification.Builder Notification.Builder} was added in Android +3.0 (API level 11).
+ +Design Considerations
+ +Notifications, as an important part of the Android user interface, have their own design guidelines. +The material design changes introduced in Android 5.0 (API level 21) are of particular +importance, and you should review the Material Design +training for more information. To learn how to design notifications and their interactions, read the +Notifications design guide.
+Creating a Notification
-- You specify the UI information and actions for a notification in a - {@link android.support.v4.app.NotificationCompat.Builder NotificationCompat.Builder} object. - To create the notification itself, you call - {@link android.support.v4.app.NotificationCompat.Builder#build - NotificationCompat.Builder.build()}, which returns a {@link android.app.Notification} object - containing your specifications. - To issue the notification, you pass the {@link android.app.Notification} object to the system - by calling {@link android.app.NotificationManager#notify NotificationManager.notify()}. -
- + +You specify the UI information and actions for a notification in a +{@link android.support.v4.app.NotificationCompat.Builder NotificationCompat.Builder} object. +To create the notification itself, you call +{@link android.support.v4.app.NotificationCompat.Builder#build NotificationCompat.Builder.build()}, +which returns a {@link android.app.Notification} object containing your specifications. To issue the +notification, you pass the {@link android.app.Notification} object to the system by calling +{@link android.app.NotificationManager#notify NotificationManager.notify()}.
+Required notification contents
A {@link android.app.Notification} object must contain the following: @@ -275,7 +151,8 @@ page.title=Notifications
Inside a {@link android.app.Notification}, the action itself is defined by a - {@link android.app.PendingIntent} containing an {@link android.content.Intent} that starts + {@link android.app.PendingIntent} containing an + {@link android.content.Intent} that starts an {@link android.app.Activity} in your application. To associate the {@link android.app.PendingIntent} with a gesture, call the appropriate method of {@link android.support.v4.app.NotificationCompat.Builder}. For example, if you want to start @@ -351,12 +228,12 @@ mNotificationManager.notify(mId, mBuilder.build());
That's it. Your user has now been notified.
-Applying a big view style to a notification
+Applying an expanded layout to a notification
- To have a notification appear in a big view when it's expanded, first create a + To have a notification appear in an expanded view, first create a {@link android.support.v4.app.NotificationCompat.Builder} object with the normal view options you want. Next, call {@link android.support.v4.app.NotificationCompat.Builder#setStyle - Builder.setStyle()} with a big view style object as its argument. + Builder.setStyle()} with an expanded layout object as its argument.
Remember that expanded notifications are not available on platforms prior to Android 4.1. To @@ -365,7 +242,7 @@ mNotificationManager.notify(mId, mBuilder.build());
For example, the following code snippet demonstrates how to alter the notification created - in the previous snippet to use the Inbox big view style: + in the previous snippet to use the expanded layout:
NotificationCompat.Builder mBuilder = new NotificationCompat.Builder(this)
@@ -375,20 +252,22 @@ NotificationCompat.Builder mBuilder = new NotificationCompat.Builder(this)
NotificationCompat.InboxStyle inboxStyle =
new NotificationCompat.InboxStyle();
String[] events = new String[6];
-// Sets a title for the Inbox style big view
+// Sets a title for the Inbox in expanded layout
inboxStyle.setBigContentTitle("Event tracker details:");
...
-// Moves events into the big view
+// Moves events into the expanded layout
for (int i=0; i < events.length; i++) {
inboxStyle.addLine(events[i]);
}
-// Moves the big view style object into the notification object.
+// Moves the expanded layout object into the notification object.
mBuilder.setStyle(inBoxStyle);
...
// Issue the notification here.
+
Handling compatibility
+Not all notification features are available for a particular version, even though the methods to set them are in the support library class @@ -419,7 +298,8 @@ mBuilder.setStyle(inBoxStyle);
Managing Notifications
@@ -444,7 +326,7 @@ mBuilder.setStyle(inBoxStyle); Notifications Design guide.- Note: This Gmail feature requires the "inbox" big view style, which is + Note: This Gmail feature requires the "inbox" expanded layout, which is part of the expanded notification feature available starting in Android 4.1.
@@ -453,8 +335,8 @@ mBuilder.setStyle(inBoxStyle);
Updating notifications
To set up a notification so it can be updated, issue it with a notification ID by - calling {@link android.app.NotificationManager#notify(int, Notification) - NotificationManager.notify(ID, notification)}. To update this notification once you've issued + calling {@link android.app.NotificationManager#notify(int, android.app.Notification) NotificationManager.notify()}. + To update this notification once you've issued it, update or create a {@link android.support.v4.app.NotificationCompat.Builder} object, build a {@link android.app.Notification} object from it, and issue the {@link android.app.Notification} with the same ID you used previously. If @@ -487,17 +369,7 @@ numMessages = 0; mNotifyBuilder.build()); ... -
- This produces a notification that looks like this: -
-
-- Figure 5. Updated notification displayed in the notification drawer. -
+Removing notifications
@@ -899,18 +771,7 @@ new Thread( // Starts the thread by calling the run() method in its Runnable ).start(); -
- The resulting notifications are shown in figure 6. On the left side is a snapshot of the - notification during the operation; on the right side is a snapshot of it after the operation - has finished. -
-
--Figure 6. The progress bar during and after the operation.
+Displaying a continuing activity indicator
@@ -946,19 +807,123 @@ mBuilder.setProgress(0, 0, true); // Issues the notification mNotifyManager.notify(0, mBuilder.build()); -
- The resulting indicator is shown in figure 7: -
-
-Figure 7. An ongoing activity indicator.
- - - +Notification Metadata
+ +Notifications may be sorted according to metadata that you assign with the +following {@link android.support.v4.app.NotificationCompat.Builder} methods:
+ +-
+
- {@link android.support.v4.app.NotificationCompat.Builder#setCategory(java.lang.String) setCategory()} + tells the system how to handle your app notifications when the device is in Priority mode + (for example, if your notification represents an incoming call, instant message, or alarm). +
- {@link android.support.v4.app.NotificationCompat.Builder#setPriority(int) setPriority()} causes + notifications with the priority field set to {@code PRIORITY_MAX} or {@code PRIORITY_HIGH} to + appear in a small floating window if the notification also has sound or vibration. +
- {@link android.support.v4.app.NotificationCompat.Builder#addPerson(java.lang.String) addPerson()} + allows you to add a list of people to a notification. Your app can use this to signal to the + system that it should group together notifications from the specified people, or rank notifications + from these people as being more important. +
+ + Figure 3. Fullscreen activity showing a heads-up notification +
+Heads-up Notifications
+ +With Android 5.0 (API level 21), notifications can appear in a small floating window +(also called a heads-up notification) when the device is active +(that is, the device is unlocked and its screen is on). These notifications +appear similar to the compact form of your notification, except that the +heads-up notification also shows action buttons. Users can act on, or dismiss, +a heads-up notification without leaving the current app.
+ +Examples of conditions that may trigger heads-up notifications include:
+ +-
+
- The user's activity is in fullscreen mode (the app uses +{@link android.app.Notification#fullScreenIntent}), or +
- The notification has high priority and uses ringtones or + vibrations +
Lock Screen Notifications
+ +With the release of Android 5.0 (API level 21), notifications may now appear on the lock +screen. Your app can use this functionality to provide media playback controls and other common +actions. Users can choose via Settings whether to display notifications on the lock screen, and +you can designate whether a notification from your app is visible on the lock screen.
+ +Setting Visibility
+ +Your app can control the level of detail visible in notifications displayed on a secure +lock screen. You call {@link android.support.v4.app.NotificationCompat.Builder#setVisibility(int) setVisibility()} +and specify one of the following values:
+ +-
+
- {@link android.support.v4.app.NotificationCompat#VISIBILITY_PUBLIC} shows the notification's + full content. +
- {@link android.support.v4.app.NotificationCompat#VISIBILITY_SECRET} doesn't show any part of + this notification on the lock screen. +
- {@link android.support.v4.app.NotificationCompat#VISIBILITY_PRIVATE} shows basic information, + such as the notification's icon and the content title, but hides the notification's full content. +
When {@link android.support.v4.app.NotificationCompat#VISIBILITY_PRIVATE} is set, you can also +provide an alternate version of the notification content which hides certain details. For example, +an SMS app might display a notification that shows You have 3 new text messages, but hides the +message contents and senders. To provide this alternative notification, first create the replacement +notification using {@link android.support.v4.app.NotificationCompat.Builder}. When you create the +private notification object, attach the replacement notification to it through the +{@link android.support.v4.app.NotificationCompat.Builder#setPublicVersion(android.app.Notification) setPublicVersion()} +method.
+ +Controlling Media Playback on the Lock Screen
+ +In Android 5.0 (API level 21) the lock screen no longer displays media controls +based on the {@link android.media.RemoteControlClient}, which is now deprecated. Instead, use the +{@link android.app.Notification.MediaStyle} template with the +{@link android.app.Notification.Builder#addAction(android.app.Notification.Action) addAction()} +method, which converts actions into clickable icons.
+ +Note: The template and the {@link android.app.Notification.Builder#addAction(android.app.Notification.Action) addAction()} +method are not included in the support library, so these features run in Android 5.0 and higher +only.
+ +To display media playback controls on the lock screen in Android 5.0, set the visibility +to {@link android.support.v4.app.NotificationCompat#VISIBILITY_PUBLIC}, as described above. Then add +the actions and set the {@link android.app.Notification.MediaStyle} template, as described in the +following sample code:
+ +
+Notification notification = new Notification.Builder(context)
+ // Show controls on lock screen even when user hides sensitive content.
+ .setVisibility(Notification.VISIBILITY_PUBLIC)
+ .setSmallIcon(R.drawable.ic_stat_player)
+ // Add media control buttons that invoke intents in your media service
+ .addAction(R.drawable.ic_prev, "Previous", prevPendingIntent) // #0
+ .addAction(R.drawable.ic_pause, "Pause", pausePendingIntent) // #1
+ .addAction(R.drawable.ic_next, "Next", nextPendingIntent) // #2
+ // Apply the media style template
+ .setStyle(new Notification.MediaStyle()
+ .setShowActionsInCompactView(1 /* #1: pause button */)
+ .setMediaSession(mMediaSession.getSessionToken())
+ .setContentTitle("Wonderful music")
+ .setContentText("My Awesome Band")
+ .setLargeIcon(albumArtBitmap)
+ .build();
+
+
+Note: The deprecation of {@link android.media.RemoteControlClient} +has further implications for controlling media. See +Media Playback Control +for more information about the new APIs for managing the media session and controlling playback.
+