docs/html/preview/features/notification-updates.jd

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">Message 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>MessageStyle</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>MessageStyle</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>