-+ Starting in Android 7.0 (API level 24), + users can respond directly to text messages or update task lists + from within the notification + dialog. On a handheld, the inline reply action appears as an additional + button + displayed in 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. The 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 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. +
+ ++ To receive user input from the notification interface to the activity you + declared in the reply action's intent: +
+ ++Bundle remoteInput = RemoteInput.getResultsFromIntent(intent); ++
+// 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;
+ }
+
+ +// 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, you can include additional + context when handling retrieved text. For example, these apps could show + multiple lines of chat history. When the user responds via {@link + android.support.v4.app.RemoteInput}, you can update the reply history + using the {@code 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 {@code 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. +
+ + + ++ Starting in Android 7.0 (API level 24), + Android 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 {@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 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.
+ + +This section provides guidelines about when to use notification groups instead +of the {@link android.app.Notification.InboxStyle InboxStyle} +notifications available in Android 6.0 and previous versions.
+ +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 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 +({@link android.app.Notification.InboxStyle InboxStyle} or +{@link android.app.Notification.BigTextStyle BigTextStyle}) to accomplish +this. +
+ ++ 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. +
+ +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. +
+ + ++ Both notification groups and remote input have been a part of the {@link + android.app.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 {@code + setRemoteInputHistory()}. +
+ ++ In order to support backward compatibility, the same APIs are available with + the support library's {@link android.support.v4.app.NotificationCompat} + class, allowing you to build notifications that works on versions of Android + less than 5.0 (API level 21). + 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. +
++ Starting from Android 7.0 (API level 24), + you can customize notification views and + still obtain system decorations like notification headers, actions, and + expandable layouts. +
+ +To enable this capability, Android provides the following APIs to style your + custom view:
+ +To use this 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 notification = new Notification.Builder() + .setSmallIcon(R.drawable.ic_stat_player) + .setLargeIcon(albumArtBitmap)) + .setCustomContentView(contentView); + .setStyle(new Notification.DecoratedCustomViewStyle()) + .build(); + ++ + + +
+ Starting in Android 7.0 (API level 24),
+ Android provides an 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();
+
+
diff --git a/docs/html/preview/images/bundles.png b/docs/html/images/android-7.0/bundles.png
similarity index 100%
rename from docs/html/preview/images/bundles.png
rename to docs/html/images/android-7.0/bundles.png
diff --git a/docs/html/preview/images/bundles_2x.png b/docs/html/images/android-7.0/bundles_2x.png
similarity index 100%
rename from docs/html/preview/images/bundles_2x.png
rename to docs/html/images/android-7.0/bundles_2x.png
diff --git a/docs/html/preview/images/inline-reply.png b/docs/html/images/android-7.0/inline-reply.png
similarity index 100%
rename from docs/html/preview/images/inline-reply.png
rename to docs/html/images/android-7.0/inline-reply.png
diff --git a/docs/html/preview/images/inline-reply_2x.png b/docs/html/images/android-7.0/inline-reply_2x.png
similarity index 100%
rename from docs/html/preview/images/inline-reply_2x.png
rename to docs/html/images/android-7.0/inline-reply_2x.png
diff --git a/docs/html/preview/images/inline-type-reply.png b/docs/html/images/android-7.0/inline-type-reply.png
similarity index 100%
rename from docs/html/preview/images/inline-type-reply.png
rename to docs/html/images/android-7.0/inline-type-reply.png
diff --git a/docs/html/preview/images/inline-type-reply_2x.png b/docs/html/images/android-7.0/inline-type-reply_2x.png
similarity index 100%
rename from docs/html/preview/images/inline-type-reply_2x.png
rename to docs/html/images/android-7.0/inline-type-reply_2x.png
diff --git a/docs/html/preview/images/notifications-1.png b/docs/html/images/android-7.0/notifications-1.png
similarity index 100%
rename from docs/html/preview/images/notifications-1.png
rename to docs/html/images/android-7.0/notifications-1.png
diff --git a/docs/html/preview/images/notifications-2.png b/docs/html/images/android-7.0/notifications-2.png
similarity index 100%
rename from docs/html/preview/images/notifications-2.png
rename to docs/html/images/android-7.0/notifications-2.png
diff --git a/docs/html/preview/images/notifications-3.png b/docs/html/images/android-7.0/notifications-3.png
similarity index 100%
rename from docs/html/preview/images/notifications-3.png
rename to docs/html/images/android-7.0/notifications-3.png
diff --git a/docs/html/preview/images/notifications-card.png b/docs/html/images/android-7.0/notifications-card.png
similarity index 100%
rename from docs/html/preview/images/notifications-card.png
rename to docs/html/images/android-7.0/notifications-card.png
diff --git a/docs/html/preview/features/notification-updates.jd b/docs/html/preview/features/notification-updates.jd
deleted file mode 100644
index fd65e120d9e50..0000000000000
--- a/docs/html/preview/features/notification-updates.jd
+++ /dev/null
@@ -1,400 +0,0 @@
-page.title=Notifications
-page.tags=notifications
-helpoutsWidget=true
-page.image=/preview/images/notifications-card.png
-
-trainingnavtop=true
-
-@jd:body
-
-Android N introduces several new APIs that allow apps to post -notifications that are highly visible and interactive.
- -Android N 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.
- -- Android N also allows you to bundle similar notifications to - appear as a single notification. To make this possible, Android N 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, 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.
- -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. -
- -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 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. -
- -- To receive user input from the notification interface to the activity you - declared in the reply action's intent: -
- --Bundle remoteInput = RemoteInput.getResultsFromIntent(intent); --
-// 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;
- }
-
- -// 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 {@link - android.support.v4.app.RemoteInput}, you can update the reply history - using the {@code 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 {@code 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. -
- -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 {@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 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.
- - -This section provides guidelines about when to use notification groups instead -of the {@link android.app.Notification.InboxStyle InboxStyle} -notifications that have been available in 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 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 -({@link android.app.Notification.InboxStyle InboxStyle} or -{@link android.app.Notification.BigTextStyle BigTextStyle}) to accomplish -this. -
- -- 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. -
- -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. -
- - -- Both notification groups and remote input have been a part of the {@link - android.app.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 {@code - setRemoteInputHistory()}. -
- -- In order to support backward compatibility, the same APIs are available with - the support library's {@link android.support.v4.app.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. -
- -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:
- -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 notification = new Notification.Builder() - .setSmallIcon(R.drawable.ic_stat_player) - .setLargeIcon(albumArtBitmap)) - .setCustomContentView(contentView); - .setStyle(new Notification.DecoratedCustomViewStyle()) - .build(); - -- -
- 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();
-