docs: Migrate notification-update to notifications docs am: bcce7873

  to: /training/articles/direct-boot.html

- from: /preview/features/scoped-folder-access.html

  to: /training/articles/scoped-directory-access.html

- from: /preview/features/notification-updates.html

  to: /guide/topics/ui/notifiers/notifications.html

    <ol>

      <li><a href="#Updating">Updating notifications</a></li>

      <li><a href="#Removing">Removing notifications</a></li>

      <li><a href="#direct">Replying to notifications</a></li>

      <li><a href="#bundle">Bundling notifications</a></li>

    </ol>

  </li>

  <li><a href="#NotificationResponse">Preserving Navigation when Starting an Activity</a>

  </li>

  <li><a href="#metadata">Notification Metadata</a></li>

  <li><a href="#Heads-up">Heads-up Notifications</a></li>

  <li><a href="#lockscreenNotification">Lock Screen Notifications</a></li>

  <li><a href="#lockscreenNotification">Lock Screen Notifications</a>

    <ol>

      <li><a href="#visibility">Setting Visibility</a></li>

      <li><a href="#controllingMedia">Controlling Media Playback on the Lock Screen</a></li>

    </ol>

  <li><a href="#CustomNotification">Custom Notification Layouts</a></li>

  </li>

  <li><a href="#CustomNotification">Customizing Notifications</a>

    <ol>

      <li><a href="#custom">Custom Views</a></li>

      <li><a href="#style">Messaging Style</a></li>

    </ol>

  </li>

</ol>

    <h2>Key classes</h2>

        all of the notifications you previously issued.

    </li>

</ul>

<!--------------------------------------------------------------- -->

<h2 id="direct">Replying to notifications</h2>

<p>

  Starting in Android 7.0 (API level 24),

  users can respond directly to text messages or update task lists

  from within the notification

  dialog. On a handheld, the inline reply action appears as an additional

  button

  displayed in 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.

</p>

<img id="fig-reply-button" src="{@docRoot}images/android-7.0/inline-reply.png"

  srcset="{@docRoot}images/android-7.0/inline-reply.png 1x,

  {@docRoot}images/android-7.0/inline-reply_2x.png 2x"

  width="400">

<p class="img-caption">

  <strong>Figure 1.</strong> 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}images/android-7.0/inline-type-reply.png"

    srcset="{@docRoot}images/android-7.0/inline-type-reply.png 1x,

    {@docRoot}images/android-7.0/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, you can 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">Bundling notifications</h2>

<p>

  Starting in Android 7.0 (API level 24),

  Android 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 {@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}images/android-7.0/bundles.png"

  srcset="{@docRoot}images/android-7.0/bundles.png 1x,

          {@docRoot}images/android-7.0/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 available in Android 6.0 and previous versions.</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>

<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 versions of Android

  less than 5.0 (API level 21).

  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="NotificationResponse">Preserving Navigation when Starting an Activity</h2>

    standard notification layout text. If you use the same style in applications that target Android

    2.3 or higher, you'll ensure that your text is visible against the display background.

</p>

<!-- ------------------------------------------------------------------------ -->

<h3 id="custom"> Custom Views</h3>

<p>

  Starting from Android 7.0 (API level 24),

  you can customize notification views and

  still obtain system decorations like notification headers, actions, and

  expandable layouts.

</p>

<p>To enable this capability, Android provides 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 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>

<!-- ----------------------------------------------------------------------- -->

<h3 id="style">Messaging Style</h3>

<p>

  Starting in Android 7.0 (API level 24),

  Android provides an 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"))

             .build();

</pre>