Android NDK development detailed explanation of notifications on Wear OS

Notifications on your watch use the same API and structure as notifications on your phone.

Notifications can appear on your watch in two ways:

Create the notification from the mobile app and it will automatically be bridged to the watch.
Create notifications from wearable apps.
In both cases, you need to use the NotificationCompat.Builder class to create the notification. When you use the builder class to build a notification, the system is responsible for displaying the notification correctly. For example, when you send notifications from a mobile app, each notification appears as a card in the notification stream.

Check out the example below to see how notifications appear. notification card

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

For best results, use one of the NotificationCompat.Style subclasses.

Note: Using RemoteViews removes custom layout notifications and the wearable only displays text and icons. However, you can create custom notifications that use a custom card layout, which is perfect for use on your watch.

Recommended notifications for wearable devices

As with all notifications, expand notifications are a great first option because they're an ideal way to grab the attention of wearable device users. Notifications appear collapsed in the notification shade to show a brief message at a glance. If the user taps the notification, it expands to reveal more scrollable content and related actions, providing an immersive experience.

You can use any NotificationCompat.Style subclass to create expanded notifications in the same way as on mobile devices. For example, a standard notification using NotificationCompat.MessagingStyle looks like this: Expanded notification

Figure 2. MessagingStyle notification example on Wear OS.

You can see that in the expanded state, the notification has multiple actions stacked at the bottom.

To see examples of NotificationCompat.BigPictureStyle, NotificationCompat.BigTextStyle, NotificationCompat.InboxStyle, and NotificationCompat.MessagingStyle, see Notification samples on GitHub.

Tip: If the notification contains a Reply action, such as notifications from messaging apps, you can enhance this behavior. For example, you can enable voice input replies directly from the wearable device, or enable predefined text replies via setChoices(). To learn more, read Add a reply button.

Avoid showing duplicate notifications

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

However, if you build a standalone watch app and a paired phone app, those apps will create duplicate notifications.

Wear OS provides a way to stop showing duplicate notifications using a bridge API. For more information, see Bridging options for notifications.

Add wearable-specific features to notifications

If you need to add wearable-specific functionality to a notification, such as hiding the app icon in the wearable notification or allowing the user to enter a text reply by speaking, you can use the NotificationCompat.WearableExtender class to specify the options. To use this API, do the following:

Create a WearableExtender instance to set wearable-specific options for the notification.
Create an instance of NotificationCompat.Builder and set the required properties for the notification, as described earlier in this guide.
Call extend() on the notification, passing in a WearableExtender. This will apply the wearable device options to the notification.
Call build() to build the notification.
Note: Some features of NotificationCompat.WearableExtender will not work if you use the framework's NotificationManager, so be sure to use NotificationCompat.

You can synchronize the closing or dismissal behavior of notifications across a user's devices. For synchronous shutdown behavior, use the setDismissalId() method. For each notification, pass a globally unique ID as a string when calling setDismissalId(). When a notification is turned off, all other notifications with the same turn off ID on your watch and paired phone will also be turned off. To retrieve the shutdown ID, use getDismissalId().

Specify wearable-only actions

If you want to provide different actions on the watch and phone, use WearableExtender.addAction(). After adding an action using this method, the wearable device will not display any additional actions added using NotificationCompat.Builder.addAction(). Actions added using WearableExtender.addAction() will only appear on the wearable device, not the phone.

The content and code examples on this page are subject to the license described in the Content License section. Java and OpenJDK are registered trademarks of Oracle and/or its affiliates.

Last updated (UTC): 2023-02-09.