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

page.title=Notifications
page.tags=notifications
helpoutsWidget=true

trainingnavtop=true

@jd:body

<div id="tb-wrapper">
<div id="tb">

<!-- 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>
</ol>

</div>
</div>

<p>The Android N Developer Preview introduces several new APIs that allow apps to post
notifications that are highly visible and interactive.</p>

<p>The 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.</p>

<p>
  The Preview also allows you to bundle similar notifications to
  appear as a single notification. To make this possible, the
  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.
</p>

<p>Last, the Preview also adds two new custom view style APIs that
allow you to leverage system decorations in your app’s customized notification
views.</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 the 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.


<img id="fig-reply-button" src="{@docRoot}preview/images/inline-reply.png">
<p class="img-caption">
  <strong>Figure 1.</strong> The Preview 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 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);

</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.
</li>

<pre>
Bundle remoteInput = RemoteInput.getResultsFromIntent(intent);
</pre>

<li>Query the bundle using the result key (provided to the {@link
  android.support.v4.app.RemoteInput.Builder} constructor).
</li>
</ol>

<p>The following code snippet illustrates how a method retrieves the input text
from a bundle:</p>

<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>

<p>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.</p>


<img id="fig-chat-history" src="{@docRoot}preview/images/inline-reply-sent.png">
<p class="img-caption">
  <strong>Figure 3.</strong> Screenshot of chat history in the notification
  shade.
</p>

<h2 id="bundle">Bundled Notifications</h2>

<p>The Preview provides developers with a new way to represent
 a queue of notifications: <em>bundled notifications</em>. 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 4.</strong> The user can progressively expand the notification
  group.
</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} 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 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.</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 the N Developer Preview does not yet
  suppress the summary for notification groups containing a single child. This
  functionality will be added in a later version of the N Developer Preview.
</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>On handhelds, notification groups are available beginning from this
Preview. However, on tablets, the notification groups API has been available since
Android Android 5.0 (API level 21). </p>

<p>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 <a href="#best-practices">guidelines</a> described above.</p>

<p>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.
 </p>

<h2 id="custom"> Custom Views</h2>
<p>Starting from this Preview, 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 noti = new Notification.Builder()
           .setSmallIcon(R.drawable.ic_stat_player)
           .setLargeIcon(albumArtBitmap))
           .setCustomContentView(contentView);
           .setStyle(new Notification.DecoratedCustomViewStyle())
           .build();

</pre>