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"));
</pre>