Merge "docs: Notification features for N" into mnc-mr-docs

page.title=N Developer Preview Notification Features

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>