Notifications on Wear OS

Notifications on watches use the same APIs and have the same structure as notifications on phones.

Notifications can appear on a watch in two ways:

  1. A mobile app creates a notification and the system automatically bridges that notification to the watch.
  2. A wearable app creates a notification.

For both scenarios, developers use the NotificationCompat.Builder class to create notifications. When you build notifications with the builder class, the system takes care of displaying notifications properly.

For example, when you issue a notification from your mobile app, each notification appears as a card on the Notification Stream.

notification-cards

Figure 1. The same notification displayed on a phone and on a watch.

Use one of the NotificationCompat.Style subclasses for the best results.

To get started, see the detailed sample on GitHub that demonstrates many mobile and wearable subclass styles.

Note: Notifications using RemoteViews are stripped of custom layouts and the wearable only displays the text and icons. However, you can create custom notifications that use custom card layouts that work well on the watch.

Recommended notifications for wearables

We recommend using expandable notifications as the starting point for all notifications, as they are a great way to engage wearable users. The collapsed state is shown in the notification tray for a short, glanceable experience. If the user taps on it, the notification expands, revealing an immersive, scrollable experience of additional content and actions.

You can Create an expandable notification the same way you would on mobile with any of the NotificationCompat.Style subclasses.

For example, a standard notification using NotificationCompat.MessagingStyle looks like this: expandable-notification

Figure 2. Example of a MessagingStyle notification on Wear OS.

You can see the notification has multiple Actions stacked at the bottom of the expanded state.

For examples of NotificationCompat.BigPictureStyle, NotificationCompat.BigTextStyle, NotificationCompat.InboxStyle, and NotificationCompat.MessagingStyle, check out the Notification sample on GitHub.

Tip: If your notifications include a "Reply" action (such as for a messaging app), you can enhance the behavior of the notification. For example, enable voice input replies directly from the wearable or pre-defined text responses with setChoices(). For more information, read Add the reply button.

Avoiding duplicate Notifications

By default, notifications are bridged from a companion phone app to any paired watches. This is a great option if you don't have a wearable app installed.

However, if you build a standalone watch app and you have a companion phone app, the apps will create duplicate notifications.

Wear OS provides a way to stop duplicate notifications with the Bridging APIs. For more information, read Bridging mode for notifications on Wear.

Add wearable specific-features to a notification

If you ever need to add wearable-specific features to a notification, such as hiding an app icon from the wearable notification or letting users dictate a text response with voice input, you can use the NotificationCompat.WearableExtender class to specify the options. To use this API, do the following:

  1. Create an instance of a WearableExtender, setting the wearable-specific options for the notification.
  2. Create an instance of NotificationCompat.Builder, setting the desired properties for your notification as described earlier in this lesson.
  3. Call extend() on the notification and pass in the WearableExtender. This applies the wearable options to the notification.
  4. Call build() to build the notification.

Note: If you use the framework's NotificationManager, some features from NotificationCompat.WearableExtender do not work, so make sure to use NotificationCompat.

You can sync dismissals (cancellations) of notifications across the user's devices. To sync a dismissal setDismissalId() method. For each notification, pass a globally unique ID, as a string, when you call the setDismissalId() method. When the notification is dismissed, all other notifications with the same dismissal ID are dismissed on the watch(es) and on the companion phone. To retrieve a dismissal ID, use getDismissalId().

Specify wearable-only actions

If you want different actions available on the watch and the phone, then use WearableExtender.addAction(). Once you add an action with this method, the wearable does not display any other actions added with NotificationCompat.Builder.addAction(). The actions added with WearableExtender.addAction() appear only on the wearable and they do not appear on the phone.