| page.title=Notifications |
| page.tags=notifications |
| helpoutsWidget=true |
| page.image=/preview/images/notifications-card.png |
| |
| trainingnavtop=true |
| |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| |
| <!-- table of contents --> |
| <h2>This document includes</h2> |
| <ol> |
| <li><a href="#direct">Direct Reply</a></li> |
| <li><a href="#bundle">Bundled Notifications</a></li> |
| <li><a href="#custom">Custom Views</a></li> |
| <li><a href="#style">Messaging Style</a></li> |
| </ol> |
| |
| </div> |
| </div> |
| |
| <p>Android N introduces several new APIs that allow apps to post |
| notifications that are highly visible and interactive.</p> |
| |
| <p>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.</p> |
| |
| <p> |
| 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. |
| </p> |
| |
| <p>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.</p> |
| |
| <p>This document highlights some of the key changes that you should take into |
| account when using the new notification features in your apps.</p> |
| |
| <h2 id="direct">Direct Reply</h2> |
| |
| <p>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. |
| |
| |
| <img id="fig-reply-button" src="{@docRoot}preview/images/inline-reply.png" |
| srcset="{@docRoot}preview/images/inline-reply.png 1x, |
| {@docRoot}preview/images/inline-reply_2x.png 2x" |
| width="400"> |
| <p class="img-caption"> |
| <strong>Figure 1.</strong> Android N adds the <strong>Reply</strong> |
| action button. |
| </p> |
| |
| <h3>Adding inline reply actions</h3> |
| |
| <p>To create a notification action that supports direct reply: |
| </p> |
| |
| <ol> |
| <li>Create an instance of {@link android.support.v4.app.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. |
| |
| <pre> |
| // 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(); |
| </pre> |
| </li> |
| <li>Attach the {@link android.support.v4.app.RemoteInput} |
| object to an action using <code>addRemoteInput()</code>. |
| |
| <pre> |
| // 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(); |
| </pre> |
| </li> |
| |
| <li>Apply the action to a notification and issue the notification. |
| |
| <pre> |
| // 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); |
| |
| </pre> |
| </li> |
| |
| </ol> |
| |
| |
| <p> The system prompts the user to input a response when they trigger the |
| notification action. </p> |
| |
| <img id="fig-user-input" src="{@docRoot}preview/images/inline-type-reply.png" |
| srcset="{@docRoot}preview/images/inline-type-reply.png 1x, |
| {@docRoot}preview/images/inline-type-reply_2x.png 2x" |
| width="300"> |
| <p class="img-caption"> |
| <strong>Figure 2.</strong> The user inputs text from the notification shade. |
| </p> |
| |
| <h3> |
| Retrieving user input from the inline reply |
| </h3> |
| |
| <p> |
| To receive user input from the notification interface to the activity you |
| declared in the reply action's intent: |
| </p> |
| |
| <ol> |
| <li>Call {@link android.support.v4.app.RemoteInput#getResultsFromIntent |
| getResultsFromIntent()} by passing the notification action’s intent as the |
| input parameter. This method returns a {@link android.os.Bundle} that |
| contains the text response. |
| |
| <pre> |
| Bundle remoteInput = RemoteInput.getResultsFromIntent(intent); |
| </pre> |
| </li> |
| |
| <li>Query the bundle using the result key (provided to the {@link |
| android.support.v4.app.RemoteInput.Builder} constructor). You can complete |
| this process and retrieve the input text by creating a method, as in the |
| following code snippet: |
| |
| <pre> |
| // 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; |
| } |
| </pre> |
| </li> |
| |
| <li>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 {@code onReceive()} method. |
| |
| <pre> |
| // 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); |
| </pre> |
| </li> |
| </ol> |
| |
| <p> |
| 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. |
| </p> |
| |
| <p> |
| 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. |
| </p> |
| |
| <h2 id="bundle">Bundled Notifications</h2> |
| |
| <p>Android N provides developers with a new way to represent |
| a queue of notifications: <i>bundled notifications</i>. This is similar to the |
| <a href="{@docRoot}training/wearables/notifications/stacks.html">Notification |
| Stacks</a> 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.</p> |
| |
| <p> |
| 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. |
| </p> |
| |
| <img id="fig-bundles" src="{@docRoot}preview/images/bundles.png" |
| srcset="{@docRoot}preview/images/bundles.png 1x, |
| {@docRoot}preview/images/bundles_2x.png 2x" |
| width="300"> |
| <p class="img-caption"> |
| <strong>Figure 3.</strong> The user can progressively expand the notification |
| group. |
| </p> |
| |
| <p class="note"> |
| <strong>Note:</strong> If the same app sends four or more notifications |
| and does not specify a grouping, the |
| system automatically groups them together. |
| </p> |
| |
| <p>To learn how to add notifications to a group, see |
| <a href="{@docRoot}training/wearables/notifications/stacks.html#AddGroup">Add |
| Each Notification to a Group</a>.</p> |
| |
| |
| <h3 id="best-practices">Best practices for bundled notifications</h3> |
| <p>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.</p> |
| |
| <h3>When to use bundled notifications</h3> |
| |
| <p>You should use notification groups only if all of the following conditions are |
| true for your use case:</p> |
| |
| <ul> |
| <li>The child notifications are complete notifications and can be displayed |
| individually without the need for a group summary.</li> |
| <li>There is a benefit to surfacing the child notifications individually. For |
| example: |
| </li> |
| <ul> |
| <li>They are actionable, with actions specific to each child.</li> |
| <li>There is more information to the child that the user wants to read.</li> |
| </ul> |
| </ul> |
| |
| <p>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.</p> |
| |
| <p> |
| 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. |
| </p> |
| |
| <h3 id ="post">Displaying bundled notifications</h3> |
| |
| <p> |
| 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. |
| </p> |
| |
| <p class="note"> |
| <strong>Note:</strong> 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. |
| </p> |
| |
| <h3>Peeking notifications</h3> |
| |
| <p>While the system usually displays child notifications as a group, you can set |
| them to temporarily appear as |
| <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html#Heads-up"> |
| heads-up notifications</a>. This feature is especially useful because it allows |
| immediate access to the most recent child and the actions associated with it. |
| </p> |
| |
| |
| <h3>Backwards compatibility</h3> |
| |
| <p> |
| 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()}. |
| </p> |
| |
| <p> |
| 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. |
| </p> |
| |
| <h2 id="custom"> Custom Views</h2> |
| <p>Starting from Android N, you can customize notification views and |
| still obtain system decorations like notification headers, actions, and |
| expandable layouts.</p> |
| |
| <p>To enable this capability, Android N adds the following APIs to style your |
| custom view:</p> |
| |
| <dl> |
| <dt> |
| {@code DecoratedCustomViewStyle()}</dt> |
| <dd> Styles notifications other than media |
| notifications.</dd> |
| <dt> |
| {@code DecoratedMediaCustomViewStyle()}</dt> |
| <dd> Styles media notifications.</dd> |
| </dl> |
| |
| <p>To use this new API, call the {@code setStyle()} method, passing to it |
| the desired custom view style.</p> |
| |
| <p>This snippet shows how to construct a custom notification object with the |
| {@code DecoratedCustomViewStyle()} method.</p> |
| |
| <pre> |
| Notification notification = new Notification.Builder() |
| .setSmallIcon(R.drawable.ic_stat_player) |
| .setLargeIcon(albumArtBitmap)) |
| .setCustomContentView(contentView); |
| .setStyle(new Notification.DecoratedCustomViewStyle()) |
| .build(); |
| |
| </pre> |
| |
| <h2 id="style">Messaging Style</h2> |
| <p> |
| Android N introduces a new API for customizing the style of a notification. |
| Using the <code>MessagingStyle</code> 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. |
| </p> |
| |
| <p> |
| The following code snippet demonstrates how to customize a notification's |
| style using the <code>MessagingStyle</code> class. |
| </p> |
| |
| <pre> |
| 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(); |
| </pre> |