docs: Migrate notification-update to notifications docs
Bug: 30224465
Change-Id: I43ded785db6c69d493965f50f798262595b2d026
diff --git a/docs/html/_redirects.yaml b/docs/html/_redirects.yaml
index 7d7282db..0dd1c89 100644
--- a/docs/html/_redirects.yaml
+++ b/docs/html/_redirects.yaml
@@ -1216,3 +1216,5 @@
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
diff --git a/docs/html/guide/topics/ui/notifiers/notifications.jd b/docs/html/guide/topics/ui/notifiers/notifications.jd
index 8c7e086..205da73 100644
--- a/docs/html/guide/topics/ui/notifiers/notifications.jd
+++ b/docs/html/guide/topics/ui/notifiers/notifications.jd
@@ -21,6 +21,8 @@
<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>
@@ -37,12 +39,18 @@
</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>
@@ -394,6 +402,305 @@
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>
@@ -987,3 +1294,69 @@
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>
+
diff --git a/docs/html/preview/images/bundles.png b/docs/html/images/android-7.0/bundles.png
similarity index 100%
rename from docs/html/preview/images/bundles.png
rename to docs/html/images/android-7.0/bundles.png
Binary files differ
diff --git a/docs/html/preview/images/bundles_2x.png b/docs/html/images/android-7.0/bundles_2x.png
similarity index 100%
rename from docs/html/preview/images/bundles_2x.png
rename to docs/html/images/android-7.0/bundles_2x.png
Binary files differ
diff --git a/docs/html/preview/images/inline-reply.png b/docs/html/images/android-7.0/inline-reply.png
similarity index 100%
rename from docs/html/preview/images/inline-reply.png
rename to docs/html/images/android-7.0/inline-reply.png
Binary files differ
diff --git a/docs/html/preview/images/inline-reply_2x.png b/docs/html/images/android-7.0/inline-reply_2x.png
similarity index 100%
rename from docs/html/preview/images/inline-reply_2x.png
rename to docs/html/images/android-7.0/inline-reply_2x.png
Binary files differ
diff --git a/docs/html/preview/images/inline-type-reply.png b/docs/html/images/android-7.0/inline-type-reply.png
similarity index 100%
rename from docs/html/preview/images/inline-type-reply.png
rename to docs/html/images/android-7.0/inline-type-reply.png
Binary files differ
diff --git a/docs/html/preview/images/inline-type-reply_2x.png b/docs/html/images/android-7.0/inline-type-reply_2x.png
similarity index 100%
rename from docs/html/preview/images/inline-type-reply_2x.png
rename to docs/html/images/android-7.0/inline-type-reply_2x.png
Binary files differ
diff --git a/docs/html/preview/images/notifications-1.png b/docs/html/images/android-7.0/notifications-1.png
similarity index 100%
rename from docs/html/preview/images/notifications-1.png
rename to docs/html/images/android-7.0/notifications-1.png
Binary files differ
diff --git a/docs/html/preview/images/notifications-2.png b/docs/html/images/android-7.0/notifications-2.png
similarity index 100%
rename from docs/html/preview/images/notifications-2.png
rename to docs/html/images/android-7.0/notifications-2.png
Binary files differ
diff --git a/docs/html/preview/images/notifications-3.png b/docs/html/images/android-7.0/notifications-3.png
similarity index 100%
rename from docs/html/preview/images/notifications-3.png
rename to docs/html/images/android-7.0/notifications-3.png
Binary files differ
diff --git a/docs/html/preview/images/notifications-card.png b/docs/html/images/android-7.0/notifications-card.png
similarity index 100%
rename from docs/html/preview/images/notifications-card.png
rename to docs/html/images/android-7.0/notifications-card.png
Binary files differ
diff --git a/docs/html/preview/features/notification-updates.jd b/docs/html/preview/features/notification-updates.jd
deleted file mode 100644
index fd65e12..0000000
--- a/docs/html/preview/features/notification-updates.jd
+++ /dev/null
@@ -1,400 +0,0 @@
-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">Messaging 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>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>
