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

page.title=Bundled 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>Android N Developer Preview introduces several new APIs that allow apps to post
notifications that are highly visible and interactive.</p>

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


<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 Android N Developer 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 serves as a summary of
   the group. The subsequent lines list the contents of the child
   notifications. The user can expand the bundle to view its notifications. The user
   can then select a notification within its bundle and perform one of its
   actions, like "reply" or "dismiss".
  </p>

<img id="fig-bundles" src="{@docRoot}preview/images/bundles.png">
<p class="img-caption">
  <strong>Figure 4.</strong> The user can expand a bundle to see its
  notifications, then expand one of those notifications to use one of its
  actions.
</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 the 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>When a group only has a single child notification, the app should in general
not post a notification group, but instead post that notification individually.
Only if it accumulates more than one child should it display the notifications
 in a group.</p>

<p>Similarly, when a user swipes away children of an expanded
notification group, the app should remove the group as soon as there is only a
single child left. It should then convert the child into a normal, single
 notification.</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 Android N Developer
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 the N Developer 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 custom view style APIs:</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>