Skip to content

Most visited

Recently visited

navigation

Notifications

Android N introduces several new APIs that allow apps to post notifications that are highly visible and interactive.

Android N extends the existing RemoteInput notification API to support inline replies on handsets. This feature allows users to quickly respond from the notification shade without visiting your app.

Android N also allows you to bundle similar notifications to appear as a single notification. To make this possible, Android N uses the existing NotificationCompat.Builder.setGroup() method. Users can expand each of the notifications, and perform actions such as reply and dismiss on each of the notifications, individually from the notification shade.

Last, Android N also adds new APIs that allow you to leverage system decorations in your app’s customized notification views. These APIs help ensure that the notification views share a consistent presentation with standard templates.

This document highlights some of the key changes that you should take into account when using the new notification features in your apps.

Direct Reply

With the Direct Reply feature in Android N, users can quickly respond to text messages or update task lists directly within the notification interface. On a handheld, the inline reply action appears as an additional button attached to the notification. When a user replies via keyboard, the system attaches the text response to the intent you had specified for the notification action and sends the intent to your handheld app.

Figure 1. Android N adds the Reply action button.

Adding inline reply actions

To create a notification action that supports direct reply:

  1. Create an instance of RemoteInput.Builder that you can add to your notification action. This class's constructor accepts a string that the system uses as the key for the text input. Later, your handheld app uses that key to retrieve the text of the input.
    // Key for the string that's delivered in the action's intent.
    private static final String KEY_TEXT_REPLY = "key_text_reply";
    String replyLabel = getResources().getString(R.string.reply_label);
    RemoteInput remoteInput = new RemoteInput.Builder(KEY_TEXT_REPLY)
            .setLabel(replyLabel)
            .build();
    
  2. Attach the RemoteInput object to an action using addRemoteInput().
    // Create the reply action and add the remote input.
    Notification.Action action =
            new Notification.Action.Builder(R.drawable.ic_reply_icon,
                    getString(R.string.label), replyPendingIntent)
                    .addRemoteInput(remoteInput)
                    .build();
    
  3. Apply the action to a notification and issue the notification.
    // Build the notification and add the action.
    Notification newMessageNotification =
            new Notification.Builder(mContext)
                    .setSmallIcon(R.drawable.ic_message)
                    .setContentTitle(getString(R.string.title))
                    .setContentText(getString(R.string.content))
                    .addAction(action))
                    .build();
    
    // Issue the notification.
    NotificationManager notificationManager =
            NotificationManager.from(mContext);
    notificationManager.notify(notificationId, newMessageNotification);
    
    

The system prompts the user to input a response when they trigger the notification action.

Figure 2. The user inputs text from the notification shade.

Retrieving user input from the inline reply

To receive user input from the notification interface to the activity you declared in the reply action's intent:

  1. Call getResultsFromIntent() by passing the notification action’s intent as the input parameter. This method returns a Bundle that contains the text response.
    Bundle remoteInput = RemoteInput.getResultsFromIntent(intent);
    
  2. Query the bundle using the result key (provided to the RemoteInput.Builder constructor). You can complete this process and retrieve the input text by creating a method, as in the following code snippet:
    // Obtain the intent that started this activity by calling
    // Activity.getIntent() and pass it into this method to
    // get the associated string.
    
    private CharSequence getMessageText(Intent intent) {
        Bundle remoteInput = RemoteInput.getResultsFromIntent(intent);
        if (remoteInput != null) {
            return remoteInput.getCharSequence(KEY_TEXT_REPLY);
        }
        return null;
     }
    
  3. Build and issue another notification, using the same notification ID that you provided for the previous notification. The progress indicator disappears from the notification interface to inform users of a successful reply. When working with this new notification, use the context that gets passed to the receiver's onReceive() method.
    // Build a new notification, which informs the user that the system
    // handled their interaction with the previous notification.
    Notification repliedNotification =
            new Notification.Builder(context)
                    .setSmallIcon(R.drawable.ic_message)
                    .setContentText(getString(R.string.replied))
                    .build();
    
    // Issue the new notification.
    NotificationManager notificationManager =
            NotificationManager.from(context);
    notificationManager.notify(notificationId, repliedNotification);
    

For interactive apps, such as chats, it could be useful to include additional context when handling retrieved text. For example, these apps could show multiple lines of chat history. When the user responds via RemoteInput, you can update the reply history using the setRemoteInputHistory() method.

The notification must be either updated or cancelled after the app has received remote input. When the user replies to a remote update using Direct Reply, do not cancel the notification. Instead, update the notification to display the user's reply. For notifications using MessagingStyle, you should add the reply as the latest message. When using other templates, you can append the user's reply to the remote-input history.

Bundled Notifications

Android N provides developers with a new way to represent a queue of notifications: bundled notifications. This is similar to the Notification Stacks feature in Android Wear. For example, if your app creates notifications for received messages, when more than one message is received, bundle the notifications together as a single group. You can use the existing Builder.setGroup() method to bundle similar notifications.

A notification group imposes a hierarchy on the notifications comprising it. At the top of that hierarchy is a parent notification that displays summary information for the group. The user can progressively expand the notification group, and the system shows more information as the user drills deeper. When the user expands the bundle, the system reveals more information for all its child notifications; when the user expands one of those notifications, the system reveals its entire content.

Figure 3. The user can progressively expand the notification group.

Note: If the same app sends four or more notifications and does not specify a grouping, the system automatically groups them together.

To learn how to add notifications to a group, see Add Each Notification to a Group.

Best practices for bundled notifications

This section provides guidelines about when to use notification groups instead of the InboxStyle notifications that have been available in earlier versions of the Android platform.

When to use bundled notifications

You should use notification groups only if all of the following conditions are true for your use case:

  • The child notifications are complete notifications and can be displayed individually without the need for a group summary.
  • There is a benefit to surfacing the child notifications individually. For example:
    • They are actionable, with actions specific to each child.
    • There is more information to the child that the user wants to read.

Examples of good use cases for notification groups include: a messaging app displaying a list of incoming messages, or an email app displaying a list of received emails.

Examples of cases where a single notification is preferable include individual messages from a single person, or a list representation of single-line text items. You can use (InboxStyle or BigTextStyle) to accomplish this.

Displaying bundled notifications

The app should always post a group summary, even if the group contains just a single child. The system will suppress the summary and directly display the child notification if it only contains a single notification. This ensures that the system can provide a consistent experience when the user swipes away children of a group.

Note: This version of Android N does not yet suppress the summary for notification groups containing a single child. This functionality will be added in a later version of Android N.

Peeking notifications

While the system usually displays child notifications as a group, you can set them to temporarily appear as heads-up notifications. This feature is especially useful because it allows immediate access to the most recent child and the actions associated with it.

Backwards compatibility

Both notification groups and remote input have been a part of the Notification API since Android 5.0 (API level 21) to support Android Wear devices. If you've already built notifications with these APIs, the only action you must take is to verify that the app behavior corresponds to the guidelines described above, and to consider implementing setRemoteInputHistory().

In order to support backward compatibility, the same APIs are available with the support library's NotificationCompat class, allowing you to build notifications that works on earlier Android versions. On handhelds and tablets, users only see the summary notification, so an app should still have an inbox style or an equivalent notification representative for the whole information content of the group. As Android Wear devices allow users to see all child notifications even on older platform levels, you should build child notifications regardless of API level.

Custom Views

Starting from Android N, you can customize notification views and still obtain system decorations like notification headers, actions, and expandable layouts.

To enable this capability, Android N adds the following APIs to style your custom view:

DecoratedCustomViewStyle()
Styles notifications other than media notifications.
DecoratedMediaCustomViewStyle()
Styles media notifications.

To use this new API, call the setStyle() method, passing to it the desired custom view style.

This snippet shows how to construct a custom notification object with the DecoratedCustomViewStyle() method.

Notification notification = new Notification.Builder()
           .setSmallIcon(R.drawable.ic_stat_player)
           .setLargeIcon(albumArtBitmap))
           .setCustomContentView(contentView);
           .setStyle(new Notification.DecoratedCustomViewStyle())
           .build();

Messaging Style

Android N introduces a new API for customizing the style of a notification. Using the MessagingStyle class, you can change several of the labels displayed on the notification, including the conversation title, additional messages, and the content view for the notification.

The following code snippet demonstrates how to customize a notification's style using the MessagingStyle class.

  Notification notification = new Notification.Builder()
             .setStyle(new Notification.MessagingStyle("Me")
                 .setConversationTitle("Team lunch")
                 .addMessage("Hi", timestamp1, null) // Pass in null for user.
                 .addMessage("What's up?", timestamp2, "Coworker")
                 .addMessage("Not much", timestamp3, null)
                 .addMessage("How about lunch?", timestamp4, "Coworker"))
             .build();
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.