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, 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.

Review the following example to see how notifications display. 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.

Note: Using RemoteViews strips notifications 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

Use expandable notifications as the starting point for all notifications, as they are a great way to engage wearable users. The collapsed state displays in the notification tray for a short, glanceable experience. If the user taps 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, using 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, you can enable voice input replies directly from the wearable or pre-defined text responses with setChoices(). For more information, read Add the reply button.

Avoid 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 a companion phone app, the apps create duplicate notifications.

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

Add wearable-specific features to a notification

If you 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 guide.
  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 don't work, so make sure to use NotificationCompat.

You can sync dismissals or cancellations of notifications across the user's devices. To sync a dismissal, use the setDismissalId() method. For each notification, pass a globally unique ID as a string when you call setDismissalId(). When the notification is dismissed, all other notifications with the same dismissal ID are dismissed on the watch 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, not on the phone.