+Android N Developer Preview introduces several new APIs that allow apps to post +notifications that are highly visible and interactive.
+ +The Android N Developer Preview extends the existing {@link android.support.v4.app.RemoteInput} +notification API to support inline replies on handsets. This feature allows users + to quickly respond from the notification shade without visiting your app.
+ ++ The N Developer Preview also allows you to bundle similar notifications to + appear as a single notification. To make this possible, the N Developer + Preview uses the existing {@link + android.support.v4.app.NotificationCompat.Builder#setGroup + 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, the N Developer Preview also adds two new custom view style APIs that +allow you to leverage system decorations in your app’s customized notification +views.
+ +This document highlights some of the key changes that you should take into + account when using the new notification features in your apps.
+ +With the Direct Reply feature in the N Developer Preview, 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. N Developer Preview adds Reply + action button. +
+ +To create a notification action that supports direct reply: +
+ ++// 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(); ++
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(); ++
+// Build the notification and add the action +Notification notification = + 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, notification); + ++
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. +
+ +To receive user input from the notification interface to the activity you +declared in the reply action's intent:
++Bundle remoteInput = RemoteInput.getResultsFromIntent(intent); ++ +
The following code snippet illustrates how a method retrieves the input text +from a bundle:
+ +
+// 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;
+ }
+
+
+Apps can apply logic to decide what actions to take on the retrieved
+text.
+For interactive apps (like chats), provide more context in the notification itself
+ (for example, multiple lines of chat history, including the user’s own messages)
+ so that the user can respond appropriately.
+When the user responds via {@link android.support.v4.app.RemoteInput},
+ include the text in the reply history with the {@code setRemoteInputHistory()}
+ method.
+
+
+![](+"{@docRoot}preview/images/inline-reply-sent.png")
+
+ Figure 3. Screenshot of chat history in the notification + shade. +
+ +The Android N Developer preview 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 {@link android.support.v4.app.NotificationCompat.Builder#setGroup} +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 serves as a summary of + the group. The subsequent lines list the contents of the child + notifications. The user can expand the bundle to view its notifications. The user + can then select a notification within its bundle and perform one of its + actions, like "reply" or "dismiss". +
+ +
++ Figure 4. The user can expand a bundle to see its + notifications, then expand one of those notifications to use one of its + actions. +
+ +To learn how to add notifications to a group, see +Add +Each Notification to a Group.
+ + +This section provides guidelines about when to use notification groups instead +of the {@link android.app.Notification.InboxStyle} notifications that have been available + in the earlier versions of the Android platform.
+You should use notification groups only if all of the following conditions are +true for your use case:
+ +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 where a single notification (InboxStyle or BigTextStyle) is preferable + include: Individual messages from a single person, or a list representation of + single-line text items.
+ +When a group only has a single child notification, the app should in general +not post a notification group, but instead post that notification individually. +Only if it accumulates more than one child should it display the notifications + in a group.
+ +Similarly, when a user swipes away children of an expanded +notification group, the app should remove the group as soon as there is only a +single child left. It should then convert the child into a normal, single + notification.
+ +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. +
+ + +On handhelds, notification groups are available beginning from Android N Developer +preview. However, on tablets, the notification groups API has been available since +Android Android 5.0 (API level 21).
+ +All Android Wear devices have this feature, regardless of API level. + The only action a Wear developer must take is to verify that the app behavior + corresponds to the guidelines described above.
+ +In order to support backward compatibility, an app should still have +an inbox style or an equivalent notification representative for the whole information + content of the group including the children on Android 5.0 and above. +For convenience, an app can usually reuse the notification group summary and define + it as an inbox-style notification, with each line corresponding to one child + notification. +
+ +Starting from the N Developer Preview, 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 custom view style APIs:
+To use this new API, call the {@code setStyle()} method, passing to it +the desired custom view style.
+ +This snippet shows how to construct a custom notification object with the +{@code DecoratedCustomViewStyle()} method.
+ ++Notification noti = new Notification.Builder() + .setSmallIcon(R.drawable.ic_stat_player) + .setLargeIcon(albumArtBitmap)) + .setCustomContentView(contentView); + .setStyle(new Notification.DecoratedCustomViewStyle()) + .build(); + +diff --git a/docs/html/preview/images/bundles.png b/docs/html/preview/images/bundles.png new file mode 100644 index 0000000000000..57d6bee1ccdb3 Binary files /dev/null and b/docs/html/preview/images/bundles.png differ diff --git a/docs/html/preview/images/inline-reply-sent.png b/docs/html/preview/images/inline-reply-sent.png new file mode 100644 index 0000000000000..623e89e3a6605 Binary files /dev/null and b/docs/html/preview/images/inline-reply-sent.png differ diff --git a/docs/html/preview/images/inline-reply.png b/docs/html/preview/images/inline-reply.png new file mode 100644 index 0000000000000..cdf5d30614f19 Binary files /dev/null and b/docs/html/preview/images/inline-reply.png differ diff --git a/docs/html/preview/images/inline-type-reply.png b/docs/html/preview/images/inline-type-reply.png new file mode 100644 index 0000000000000..6870bc223966a Binary files /dev/null and b/docs/html/preview/images/inline-type-reply.png differ