docs/html/wear/preview/features/notifications.jd

page.title=Notification Changes in Android Wear 2.0
meta.tags="wear", "wear-preview", "notifications" page.tags="wear"
page.image=/wear/preview/images/expanded_diagram.png


@jd:body

<div id="qv-wrapper">
  <div id="qv">
    <!-- table of contents -->
    <h2>This document includes</h2>
    <ol>
      <li><a href="#visual">Visual Updates</a></li>
      <li><a href="#inline">Inline Action</a></li>
      <li><a href="#expanded">Expanded Notifications</a></li>
      <li><a href="#messaging">MessagingStyle</a></li>
    </ol>
  </div>
</div>

<p>Android Wear 2.0 updates the visual style and interaction paradigm of notifications
  as well as introduces expanded notifications, which provide substantial additional
  content and actions in an app-like experience.
</p>

<p>The visual and interaction changes make it much easier for users to read and
  interact with notifications from your app. Expanded notifications enable
  you to deliver Wear users an app-like experience even if you haven't built an
  Android Wear app.
</p>

<p class="note">
  <strong>Note:</strong> When developing for Wear 2.0, ensure that
  you have the latest version of the Android Wear app on your phone.
</p>

<h2 id="visual">Visual Updates</h2>
<p>Notifications receive important visual updates in Wear 2.0, with
<a href="http://www.google.com/design/spec-wear">
material design</a> visual changes.
</p>

<p><img src="{@docRoot}wear/preview/images/comparison_diagram.png" /> </p>
<p><b>Figure 1.</b> Comparison of the same notification in Android Wear 1.x and 2.0.</p>

<p>Some of the visual updates include:</p>
<ul>
<li><strong>Updated touch targets of a notification</strong>:
  If no <a href="{@docRoot}reference/android/app/Notification.html#contentIntent">{@code contentIntent}</a>
  is set or if the notification is
  <a href="{@docRoot}design/wear/structure.html#Bridged">bridged</a>
  from a paired phone, then tapping the notification opens an <a href="{@docRoot}wear/preview/features/notifications.html#expanded">expanded notification</a>.
  If the notification is generated locally by a Wear app and if a
  <a href="{@docRoot}reference/android/app/Notification.html#contentIntent">{@code contentIntent}</a>
  is set, tapping the notification fires the
  <a href="{@docRoot}reference/android/app/Notification.html#contentIntent">{@code contentIntent}</a>.
  </li>

<li><strong>Dark background color</strong>:
  If you have notifications that are bridged to wearables, you need to be careful
   with regards to using color for the notifications. Since a bridged
  notification needs to support both light (Wear 1.x) and dark (Wear 2.0)
  backgrounds, it is unlikely that any colors will work well on both.
  <a href="{@docRoot}reference/android/app/Notification.WearableExtender.html#setDisplayIntent(android.app.PendingIntent)">{@code DisplayIntent}</a>
   notifications render with both light and dark backgrounds
  as well, and need to be checked for the same reason.
  We recommended that you don't set color for bridged notifications.

  When Wear apps post local notifications, you can work around this by checking
  <a href="{@docRoot}training/basics/supporting-devices/platforms.html#version-codes">the API level of the device</a>
   they're running on and using an appropriate color
  for Wear 1.x and a different color for Wear 2.0.
</li>

<li><strong>Updated horizontal swipe gesture on a notification</strong>:
  To dismiss a notification in Wear 2.0, the user swipes horizontally in either
  direction. So if your notification instructs the user to swipe left or right,
  you must update the text of your notification.
</li>
</ul>

<h2 id="inline">Inline Action</h3>

<img src="{@docRoot}wear/preview/images/inline_action.png" style="float:right;margin:10px 20px 0 0">
<p>
  Wear 2.0 now supports inline action, which allows users to take actions on a
  notification from within the notification stream card.  On Wear, the inline
  action appears as an additional button displayed at the bottom of the notification.
</p>
<p>
  Inline actions are optional but recommended for cases in which users are likely
  to take an action on a notification after viewing the contents in the
  notification stream card (without going to the
  <a href= "{@docRoot}wear/preview/features/notifications.html#expanded">expanded notification</a>).
  Examples of good use cases for inline action on a notification include: replying to a
  text message, stopping a fitness activity, and archiving an email message.
</p>

<p>
  A notification can provide only one inline action.
  To display the inline action as an additional button in the notification, set
  the <a href="https://developer.android.com/reference/android/support/v4/app/NotificationCompat.Action.WearableExtender.html#setHintDisplayActionInline(boolean)">{@code setHintDisplayActionInline()}</a>
  method to true. When a user taps the inline action, the system invokes
  the intent that you specified in the notification action.
</p>

<h3>Adding an inline action</h3>
<p>
  The following code example shows how to create a notification with an inline
  reply action:
</p>

<ol>
  <li>Create an instance of
    <a href="https://developer.android.com/reference/android/support/v4/app/RemoteInput.Builder.html">{@code RemoteInput.Builder}</a></code>
    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 app
    uses that key to retrieve the text of the input.

<pre>
String[] choices = context.getResources().getStringArray(R.array.notification_reply_choices);
    choices = WearUtil.addEmojisToCannedResponse(choices);
  RemoteInput remoteInput = new RemoteInput.Builder(Intent.EXTRA_TEXT)
        .setLabel(context.getString(R.string.notification_prompt_reply))
        .setChoices(choices)
        .build();
</pre>

  </li>

  <li>
    Use the <a href="https://developer.android.com/reference/android/support/v4/app/NotificationCompat.Action.Builder.html#addRemoteInput(android.support.v4.app.RemoteInput)">{@code addRemoteInput()}</a>
    method to attach the <ahref="https://developer.android.com/reference/android/support/v4/app/RemoteInput.html">{@code RemoteInput}</a>
    object to an action.

<pre>
NotificationCompat.Action.Builder actionBuilder = new NotificationCompat.Action.Builder(
        R.drawable.ic_full_reply, R.string.notification_reply, replyPendingIntent);
    actionBuilder.addRemoteInput(remoteInput);
    actionBuilder.setAllowGeneratedReplies(true);
</pre>
  </li>

  <li>
    Add a hint to display the reply action inline, and use the
    <a href="https://developer.android.com/reference/android/support/v4/app/NotificationCompat.WearableExtender.html#addAction(android.support.v4.app.NotificationCompat.Action)">{@code addAction}</a>
    method to add this action to the notification.

<pre>
// Android Wear 2.0 requires a hint to display the reply action inline.
    Action.WearableExtender actionExtender =
        new Action.WearableExtender()
            .setHintLaunchesActivity(true)
            .setHintDisplayActionInline(true);
    wearableExtender.addAction(actionBuilder.extend(actionExtender).build());
</pre>
  </li>
</ol>

<h2 id="expanded">Expanded Notifications</h2>
<p>Android Wear 2.0 introduces <i>expanded notifications</i>, which provide
  substantial additional content and actions for each notification.
</p>
<p>When you <a href="{@docRoot}training/wearables/notifications/pages.html">specify additional content pages</a>
 and actions for a notification, those are available to the user within the
 expanded notification. Each expanded notification follows
 <a href="http://www.google.com/design/spec-wear">Material Design for Android Wear</a>,
  so the user gets an app-like experience.
</p>


<h3 id="expanded">Expanded notifications</h3>
<p>If the first action in the expanded notification has a
<a href=" {@docRoot}reference/android/support/v4/app/RemoteInput.html">{@code RemoteInput}</a>
  (e.g., a Reply action), then the choices you set with <a href="http://developer.android.com/reference/android/support/v4/app/RemoteInput.Builder.html#setChoices(java.lang.CharSequence[])">{@code setChoices()}</a>
  appear within the expanded notification below the first action.
</p>

<p>The user can view the expanded notification by tapping on a notification when
  either of the following is true:
</p>
<ul>
  <li>The notification is generated by an app on the paired phone and
    bridged to Wear.
  </li>
  <li>The notification does not have a
  <a href="http://developer.android.com/reference/android/support/v4/app/NotificationCompat.Builder.html#setContentIntent(android.app.PendingIntent)">{@code contentIntent}</a>.
  </li>
</ul>
<h3>Best practices for expanded notifications</h3>
<p>To decide when to use expanded notifications, follow these guidelines:</p>
<ul>
  <li>All notifications bridged from the paired phone to the Wear device will
  use expanded notifications.
  </li>
  <li>If a notification is generated by an app running locally on Wear 2.0,
    you should <a href="{@docRoot}training/notify-user/build-notification.html#action">
    make the touch target of your notification </a> launch
    <a href="{@docRoot}training/notify-user/build-notification.html#action"> an Activity</a>
    within your app by calling <a href="{@docRoot}reference/android/support/v4/app/NotificationCompat.Builder.html#setContentIntent(android.app.PendingIntent)">{@code setContentIntent()}</a>.
    We recommend that you do not use expanded notifications for notifications generated
    by an app running locally on Wear 2.0.
  </li>
</ul>

<h3>Adding expanded notifications</h3>
<p>
 Expanded Notifications allow you to include additional content and actions
   for a notification. You choose the level of detail that your app's notifications
    will provide; however be judicious with the amount of detail you include in a
    notification.
</p>
<img src="{@docRoot}wear/preview/images/expanded_diagram.png" height="340"
  style="float:left;margin:10px 20px 0 0" />
<h4>Adding additional content</h4>
To show additional content in your expanded notification, see <a href="{@docRoot}training/wearables/notifications/pages.html">Adding Pages to a Notification</a>.</p>
<p>Additional content pages are stacked vertically in the expanded notification
 and appear in the order they were added.
  These additional content pages can optionally use a style such as <a href="{@docRoot}reference/android/support/v4/app/NotificationCompat.BigTextStyle.html">{@code BigTextStyle}</a> or <a href="{@docRoot}reference/android/support/v4/app/NotificationCompat.BigPictureStyle.html">{@code BigPictureStyle}</a>.
</p>
<h4>Primary action</h4>
The expanded notification will contain one primary action, which is the first
action in the notification unless a different action is specified using
<a href="{@docRoot}reference/android/support/v4/app/NotificationCompat.WearableExtender.html#setContentAction(int)">{@code setContentAction()}</a>.
</p>
<h4>Additional actions</h4>
<p>
  To specify additional actions, use
  <a href="{@docRoot}reference/android/support/v4/app/NotificationCompat.WearableExtender.html#addAction(android.support.v4.app.NotificationCompat.Action)">{@code addAction()}</a>
   or <a href="{@docRoot}reference/android/support/v4/app/NotificationCompat.WearableExtender.html#addActions(java.util.List<android.support.v4.app.NotificationCompat.Action>)">{@code addActions()}</a>.
    The action drawer of the expanded notification contains all available actions.
</p>
<h2 id="messaging">MessagingStyle</h2>

<p>
  If you have a chat messaging app, your notifications should use
  <a href="https://developer.android.com/reference/android/support/v4/app/NotificationCompat.MessagingStyle.html">{@code NotificationCompat.MessagingStyle}</a>,
  which is new in Android 7.0. Wear 2.0 uses the chat messages included in a
  {@code MessagingStyle} notification
  (see <a href="https://developer.android.com/reference/android/support/v4/app/NotificationCompat.MessagingStyle.html#addMessage(android.support.v4.app.NotificationCompat.MessagingStyle.Message)">{@code addMessage()}</a>)
  to provide a rich chat app-like experience in the expanded notification.
</p>

<p class="note">Note: <a href="https://developer.android.com/reference/android/support/v4/app/NotificationCompat.MessagingStyle.html">{@code MessagingStyle}</a>
expanded notifications require that you have at least version 1.5.0.2861804 of the
  <a href="https://play.google.com/store/apps/details?id=com.google.android.wearable.app">Android Wear app</a>
  on your paired Android phone.
</p>

<h3 id="smart-reply">Smart Reply</h3>
<img src="{@docRoot}wear/preview/images/messaging_style.png" height="420"
  style="float:right;margin:10px 20px 0 0" />
<p>Wear 2.0 also introduces <i>Smart Reply</i> for
  <a href="https://developer.android.com/reference/android/support/v4/app/NotificationCompat.MessagingStyle.html">{@code MessagingStyle}</a> notifications.
  Smart Reply provides the user with contextually relevant, touchable choices in
  the expanded notification and in {@code RemoteInput}. These augment the fixed
  list of choices that the developer provides in
  <a href="http://developer.android.com/reference/android/support/v4/app/RemoteInput.html">{@code RemoteInput}</a>
  using the
  <a href="{@docRoot}reference/android/support/v4/app/RemoteInput.Builder.html#setChoices(java.lang.CharSequence[])">{@code setChoices()}</a> method.
</p>
<p> Smart Reply provides users with a fast (single tap), discreet (no speaking aloud),
  private (messages received by a user never leave the watch), and reliable (no
  internet connection needed) way to respond to chat messages.
</p>

<p>
  Smart Reply responses are generated by an entirely on-watch machine learning
  model using the context provided by the MessagingStyle notification. No user
  notification data is sent to Google servers to generate Smart Reply responses.
</p>

<p>To enable Smart Reply for your notification action, you need to do the
following:
</p>
<ol>
  <li>Use <a href="https://developer.android.com/reference/android/support/v4/app/NotificationCompat.MessagingStyle.html">{@code NotificationCompat.MessagingStyle}</a>.
  </li>
  <li>Call the method <a href="https://developer.android.com/reference/android/support/v4/app/NotificationCompat.Action.Builder.html#setAllowGeneratedReplies(boolean)">{@code setAllowGeneratedReplies(true)}</a>
   for the notification action.
  </li>
  <li>Ensure that the notification action has a
    <a href="{@docRoot}reference/android/app/RemoteInput.html">{@code RemoteInput}</a>
     (where the responses will reside).
  </li>
</ol>
<p>The following example shows how to create a MessagingStyle notification with
Smart Reply responses.</p>
<pre>
// Create an intent for the reply action
Intent replyIntent = new Intent(this, ReplyActivity.class);
PendingIntent replyPendingIntent =
 PendingIntent.getActivity(this, 0, replyIntent,
  PendingIntent.FLAG_UPDATE_CURRENT);

// Create the reply action and add the remote input
NotificationCompat.Action action =
 new NotificationCompat.Action.Builder(R.drawable.ic_reply_icon,
  getString(R.string.label), replyPendingIntent)
 .addRemoteInput(remoteInput)

// 1) allow generated replies
.setAllowGeneratedReplies(true)
 .build();

Notification noti = new NotificationCompat.Builder()
 .setContentTitle(messages.length + " new messages with " + sender.toString())
 .setContentText(subject)
 .setSmallIcon(R.drawable.new_message)
 .setLargeIcon(aBitmap)
 // 2) set the style to MessagingStyle
 .setStyle(new NotificationCompat.MessagingStyle(resources.getString(R.string.reply_name))
 .addMessage(messages[0].getText(), messages[0].getTime(), messages[0].getSender())
 .addMessage(messages[1].getText(), messages[1].getTime(), messages[1].getSender()))


// 3) add an action with RemoteInput
.extend(new WearableExtender().addAction(action)).build();
</pre>

<h3 id="images">Adding images to a MessagingStyle notification</h3>
<p>
  You can add images to a notification message  by setting the appropriate MIME
  type and placing the URI to the image in {@code NotificationCompat.MessagingStyle.Message.}
  <a href="https://developer.android.com/reference/android/support/v4/app/NotificationCompat.MessagingStyle.Message.html#setData(java.lang.String, android.net.Uri)">{@code setData()}</a> method.
</p>
<p>
  Here is the code snippet to set data of type image in a notification:
</p>
<pre>
NotificationCompat.MessagingStyle.Message message = new Message("sticker", 1, "Jeff")
                      .setData("image/png", stickerUri);

  NotificationCompat notification = new NotificationCompat.Builder()
             .setStyle(new NotificationComapt.MessagingStyle("Me")
             .addMessage(message)
             .build());

</pre>
<p>
  In the above code snippet the variable <code>stickerUri </code>is a Uri that
  points to a publicly-accessible location, as described <a
  href="https://developer.android.com/reference/android/support/v4/app/NotificationCompat.MessagingStyle.Message.html">here
  </a>.
</p>