Android: notifications

android-sdk/docs/guide/topics/ui/notifiers/notifications.html

Notifications

IN THIS DOCUMENT

1. Notification Display Elements
   1. Normal view
   2. Big view
2. Creating a Notification
   1. Required notification contents
   2. Optional notification contents and settings
   3. Notification actions
   4. Creating a simple notification
   5. Applying a big view style to a notification
   6. Handling compatibility
3. Managing Notifications
   1. Updating notifications
   2. Removing notifications
4. Preserving Navigation when Starting an Activity
   1. Setting up a regular activity PendingIntent
   2. Setting up a special activity PendingIntent
5. Displaying Progress in a Notification
   1. Displaying a fixed-duration progress indicator
   2. Displaying a continuing activity indicator
6. Custom Notification Layouts

KEY CLASSES

1. NotificationManager
2. NotificationCompat

VIDEOS

1. Notifications in 4.1

SEE ALSO

1. Android Design: Notifications

A notification is a message you can display to the user outside of your application's normal UI. When you tell the system to issue a notification, it first appears as an icon in the notification area. To see the details of the notification, the user opens the notification drawer. Both the notification area and the notification drawer are system-controlled areas that the user can view at any time.

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 theNotificationCompat.Builder class in the version 4 Support Library. The class 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:

1. Content title
2. Large icon
3. Content text
4. Content info
5. Small icon
6. Time that the notification was issued. You can set an explicit value with 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.

Creating a Notification

---

You specify the UI information and actions for a notification in a NotificationCompat.Builder object. To create the notification itself, you call NotificationCompat.Builder.build(), which returns aNotification object containing your specifications. To issue the notification, you pass the Notificationobject to the system by calling NotificationManager.notify().

Required notification contents

A Notification object must contain the following:

• A small icon, set by setSmallIcon()
• A title, set by setContentTitle()
• Detail text, set by setContentText()

Optional notification contents and settings

All other notification settings and contents are optional. To learn more about them, see the reference documentation for NotificationCompat.Builder.

Notification actions

Although they're optional, you should add at least one action to your notification. An action allows users to go directly from the notification to an Activity in your application, where they can look at one or more events or do further work.

A notification can provide multiple actions. You should always define the action that's triggered when the user clicks the notification; usually this action opens an Activity in your application. You can also add buttons to the notification that perform additional actions such as snoozing an alarm or responding immediately to a text message; this feature is available as of Android 4.1. If you use additional action buttons, you must also make their functionality available in an Activity in your app; see the section Handling compatibility for more details.

Inside a Notification, the action itself is defined by a PendingIntent containing an Intent that starts anActivity in your application. To associate the PendingIntent with a gesture, call the appropriate method ofNotificationCompat.Builder. For example, if you want to start Activity when the user clicks the notification text in the notification drawer, you add the PendingIntent by calling setContentIntent().

Starting an Activity when the user clicks the notification is the most common action scenario. You can also start an Activity when the user dismisses an Activity. In Android 4.1 and later, you can start an Activityfrom an action button. To learn more, read the reference guide for NotificationCompat.Builder.

Creating a simple notification

The following snippet illustrates a simple notification that specifies an activity to open when the user clicks the notification. Notice that the code creates a TaskStackBuilder object and uses it to create the PendingIntentfor the action. This pattern is explained in more detail in the section Preserving Navigation when Starting an Activity:

NotificationCompat.Builder mBuilder =
        new NotificationCompat.Builder(this)
        .setSmallIcon(