Skip to content

Most visited

Recently visited

navigation

Creating a Notification for Wearables

With the introduction of standalone Wear apps, both the watch and the phone can be sources of notifications. Use the NotificationCompat.Builder class to create notifications for wearables. When you build notifications with this class, the system takes care of displaying notifications properly, whether they appear on a watch or phone.

This document shows you how to create and issue a notification for wearables. It also explains how to provide additional content for each notification that is bridged to the wearable from a connected phone, and how to add actions and wearable-specific features to a notification.

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 by creating a wearable app that runs on the watch.

Import the necessary classes

To import the necessary packages, add this line to your build.gradlefile:

compile "com.android.support:support-v4:25.0.+"

Now that your project has access to the necessary packages, import the necessary classes from the support library:

import android.support.v4.app.NotificationCompat;
import android.support.v4.app.NotificationManagerCompat;
import android.support.v4.app.NotificationCompat.WearableExtender;

Create a Notification with the Notification Builder

The v4 support library allows you to create notifications using the latest notification features such as action buttons and icons, while remaining compatible with Android 1.6 (API level 4) and higher.

Note: Starting in Android 8.0 (API level 26), you need to create notification channels for each type of notification you want to display.

To create a notification with the support library:

  1. You create an instance of NotificationCompat.Builder.
    int notificationId = 001;
    // The channel ID of the notification.
    String id = "my_channel_01";
    // Build intent for notification content
    Intent viewIntent = new Intent(this, ViewEventActivity.class);
    viewIntent.putExtra(EXTRA_EVENT_ID, eventId);
    PendingIntent viewPendingIntent =
            PendingIntent.getActivity(this, 0, viewIntent, 0);
    
    // Notification channel ID is ignored for Android 7.1.1
    // (API level 25) and lower.
    NotificationCompat.Builder notificationBuilder =
        new NotificationCompat.Builder(this, id)
            .setSmallIcon(R.drawable.ic_event)
            .setContentTitle(eventTitle)
            .setContentText(eventLocation)
            .setContentIntent(viewPendingIntent);
    
  2. Issue the notification by passing the Notification object with a notification ID to notify().
    // Get an instance of the NotificationManager service
    NotificationManagerCompat notificationManager =
            NotificationManagerCompat.from(this);
    
    // Issue the notification with notification manager.
    notificationManager.notify(notificationId, notificationBuilder.build());
    

When this notification appears on a phone, the user can invoke the PendingIntent specified by the setContentIntent() method by touching the notification. When this notification appears on an Android wearable, it appears in the notification stream. For bridged notifications, the user can click the notification to view the expanded notification and trigger any defined action, such as open action. Usually, these actions opens an Activity on your phone app.

Construct Expanded notifications

Expanded notifications provide substantial additional content and actions for each notification. When you specify additional content pages and actions for a notification, those are available to the user within the expanded notification. Each expanded notification follows Material Design for Android Wear, so the user gets an app-like experience.

If the first action in the expanded notification has a RemoteInput (e.g., a Reply action), then the choices you set with setChoices() appear within the expanded notification below the first action.

The user can view the expanded notification by tapping on a notification when either of the following is true:

Note: An app-specific background color set for a notification with the setColor() method is shown only when you expand the notification.

Best practices for expanded notifications

To decide when to use expanded notifications, follow these guidelines:

Adding expanded notifications

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.

Adding additional content

To show additional text in your expanded notification, use the BigTextStyle.

To add images in your expanded notification, you can use the BigPictureStyle. If you want to add more than one image in your expanded notification, use the addPage() method along with the BigPictureStyle.

Primary action

The expanded notification will contain one primary action, which is the first action in the notification unless a different action is specified using setContentAction().

Additional actions

To specify additional actions, use addAction() or addActions(). The action drawer of the expanded notification contains all available actions.

Add Notification Actions

In addition to the primary content action defined by setContentIntent(), you can add other actions by passing a PendingIntent to the addAction() method.

For example, the following code shows the same type of notification from above, but adds an action to view the event location on a map.

// Build an intent for an action to view a map
Intent mapIntent = new Intent(Intent.ACTION_VIEW);
// The channel ID of the notification.
String id = "my_channel_01";
Uri geoUri = Uri.parse("geo:0,0?q=" + Uri.encode(location));
mapIntent.setData(geoUri);
PendingIntent mapPendingIntent =
        PendingIntent.getActivity(this, 0, mapIntent, 0);

NotificationCompat.Builder notificationBuilder =
        new NotificationCompat.Builder(this, id)
        .setSmallIcon(R.drawable.ic_event)
        .setContentTitle(eventTitle)
        .setContentText(eventLocation)
        .setContentIntent(viewPendingIntent)
        .addAction(R.drawable.ic_map,
                getString(R.string.map), mapPendingIntent);

On a phone, the action appears as an additional button attached to the notification. On a wearable, the action appears in the expanded notification after the content text. When the user taps the action, the associated intent is invoked on the phone.

Tip: If your notifications include a "Reply" action (such as for a messaging app), you can enhance the behavior by enabling voice input replies directly from the Android wearable. For more information, read Adding Voice Input as a notification action.

Adding an Inline Action

Inline action 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.

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 expanded notification). 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.

A notification can provide only one inline action. To display the inline action as an additional button in the notification, set the setHintDisplayActionInline() method to true. When a user taps the inline action, the system invokes the intent that you specified in the notification action.

The following code snippet adds a hint to display an action inline, and uses the addAction method to add the inline action to a notification.

//Android Wear 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());

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:

  1. Create an instance of a WearableExtender, setting the wearable-specific options for the notication.
  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.

For example, the following code calls the setHintHideIcon() method to remove the app icon from the notification card.

// Create a WearableExtender to add functionality for wearables
NotificationCompat.WearableExtender wearableExtender =
        new NotificationCompat.WearableExtender()
        .setHintHideIcon(true);

// Create a NotificationCompat.Builder to build a standard notification
// then extend it with the WearableExtender
Notification notif = new NotificationCompat.Builder(mContext)
        .setContentTitle("New mail from " + sender)
        .setContentText(subject)
        .setSmallIcon(R.drawable.new_mail)
        .extend(wearableExtender)
        .build();

The setHintHideIcon() method is an example of one of many notification features available with NotificationCompat.WearableExtender.

Note: The setBackground() method is not supported on Wear 2.0. You can use NotificationCompat.BigPictureStyle for notifications that include images.

If you ever need to read wearable-specific options at a later time, use the corresponding get method for the option. This example calls the getHintHideIcon() method to get whether or not this notification hides the icon:

NotificationCompat.WearableExtender wearableExtender =
        new NotificationCompat.WearableExtender(notif);
boolean hintHideIcon = wearableExtender.getHintHideIcon();

Specify Wearable-only Actions

If you want the actions available on the wearable to be different from those on 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.

Adding voice input as a notification action

Voice actions are an important part of the wearable experience. To create an action that supports voice input, create an instance of 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 voice input, which you'll later use to retrieve the text of the input in your phone app.

For example, here's how to create a RemoteInput object that provides a custom label for the voice input prompt:

// Key for the string that's delivered in the action's intent
private static final String EXTRA_VOICE_REPLY = "extra_voice_reply";

String replyLabel = getResources().getString(R.string.reply_label);

RemoteInput remoteInput = new RemoteInput.Builder(EXTRA_VOICE_REPLY)
        .setLabel(replyLabel)
        .build();

Add Pre-defined Text Responses

In addition to allowing voice input, you can provide up to five text responses that the user can select for quick replies. Call setChoices() and pass it a string array.

For example, you can define some responses in a resource array:

res/values/strings.xml

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string-array name="reply_choices">
        <item>Yes</item>
        <item>No</item>
        <item>Maybe</item>
    </string-array>
</resources>

Then, inflate the string array and add it to the RemoteInput:

public static final String EXTRA_VOICE_REPLY = "extra_voice_reply";
...
String replyLabel = getResources().getString(R.string.reply_label);
String[] replyChoices = getResources().getStringArray(R.array.reply_choices);

RemoteInput remoteInput = new RemoteInput.Builder(EXTRA_VOICE_REPLY)
        .setLabel(replyLabel)
        .setChoices(replyChoices)
        .build();

Receiving the voice input as a string

To receive the user's transcribed message in the activity you declared in the reply action's intent, call getResultsFromIntent(), passing in the "Reply" action's intent. This method returns a Bundle that contains the text response. You can then query the Bundle to obtain the response.

Note: Do not use Intent.getExtras() to obtain the voice result, because the voice input is stored as ClipData. The getResultsFromIntent() method provides a convenient way to receive a character sequence without having to process the ClipData yourself.

The following code shows a method that accepts an intent and returns the voice response, which is referenced by the EXTRA_VOICE_REPLY key that is used in the previous examples:

/**
 * Obtain the intent that started this activity by calling
 * Activity.getIntent() and pass it into this method to
 * get the associated voice input string.
 */

private CharSequence getMessageText(Intent intent) {
    Bundle remoteInput = RemoteInput.getResultsFromIntent(intent);
    if (remoteInput != null) {
        return remoteInput.getCharSequence(EXTRA_VOICE_REPLY);
    }
    return null;
}
// Create an intent for the reply action
Intent actionIntent = new Intent(this, ActionActivity.class);
PendingIntent actionPendingIntent =
        PendingIntent.getActivity(this, 0, actionIntent,
                PendingIntent.FLAG_UPDATE_CURRENT);

// Create the action
NotificationCompat.Action action =
        new NotificationCompat.Action.Builder(R.drawable.ic_action,
                getString(R.string.label), actionPendingIntent)
                .build();

// Build the notification and add the action via WearableExtender
Notification notification =
        new NotificationCompat.Builder(mContext)
                .setSmallIcon(R.drawable.ic_message)
                .setContentTitle(getString(R.string.title))
                .setContentText(getString(R.string.content))
                .extend(new WearableExtender().addAction(action))
                .build();

Launch Notifications From Standalone Wearable Apps

Creating notifications from a standalone watch app is no different from creating bridged notifications. Notifications sourced from a standalone Wear app look similar to bridged notifications but they behave slightly differently. If no contentIntent is set or if the notification is bridged from a paired phone, then tapping the notification opens an expanded notification. Whereas, if the notification is originating from a standalone watch app, then tapping the notification fires the contentIntent to open your Wear app. To learn how to create notifications from a standalone app and mimic the expanded notification behavior, see the Wear Notifications sample.

By default, notifications are bridged from an app on a companion phone to the paired watch. If you build a standalone watch app and you have a companion phone app, the apps may create duplicate notifications. For information on handling the problem of duplicate notifications, see Bridging Mode for Notifications.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)