Creating Notifications for Android Wear

When an Android device such as a phone or tablet is connected to an Android wearable, all notifications are shared between the devices by default. On the Android wearable, each notification appears as a new card in the context stream.

So without any effort, your app notifications are available to users on Android Wear. However, you can enhance the user experience in several ways. For instance, if users may respond to a notification by entering text, such as to reply to a message, you can add the ability for users to reply by voice directly from the wearable.

To help you provide the best user experience for your notifications on Android Wear, this guide shows you how to build notifications using standard templates in the NotificationCompat.Builder APIs, plus how to begin extending your notification's capabilities for the wearable user experience.

Note: Notifications using RemoteViews are stripped of custom layouts and the system uses only the text and icons in the Notification object to display the notification in a card. However, custom card layouts will be supported by the official Android Wear SDK that is coming later.

Import the Necessary Classes

To begin development, you must first complete the instructions in the Get Started with the Developer Preview document. As mentioned in that document, your app must include both the v4 support library and the Developer Preview support library. So to get started, you should include the following imports in your project code:

import android.support.wearable.notifications.*;
import android.support.wearable.app.NotificationManagerCompat;
import android.support.v4.app.NotificationCompat;

Caution: The APIs in the current Android Wear Developer Preview are intended for development and testing purposes only, not for production apps. Google may change this Developer Preview significantly prior to the official release of the Android Wear SDK. You may not publicly distribute or ship any application using this Developer Preview, as this Developer Preview will no longer be supported after the official SDK is released (which will cause applications based only on the Developer Preview to break).

Create Notifications with the Notification Builder

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

For example, here's some code that creates and issues a notification using the NotificationCompat APIs combined with the new NotificationManagerCompat API:

int notificationId = 001;
// 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);

NotificationCompat.Builder notificationBuilder =
        new NotificationCompat.Builder(this)
        .setSmallIcon(R.drawable.ic_event)
        .setContentTitle(eventTitle)
        .setContentText(eventLocation)
        .setContentIntent(viewPendingIntent);

// Get an instance of the NotificationManager service
NotificationManagerCompat notificationManager =
        NotificationManagerCompat.from(this);

// Build the notification and issues it with notification manager.
notificationManager.notify(notificationId, notificationBuilder.build());

When this notification appears on a handheld device, the user can invoke the PendingIntent specified by the setContentIntent() method by touching the notification. When this notification appears on an Android wearable, the user can swipe the notification to the left to reveal the Open action, which invokes the intent on the handheld device.

Add Action Buttons

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);
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)
        .setSmallIcon(R.drawable.ic_event)
        .setContentTitle(eventTitle)
        .setContentText(eventLocation)
        .setContentIntent(viewPendingIntent)
        .addAction(R.drawable.ic_map,
                getString(R.string.map), mapPendingIntent);

On a handheld device, the action appears as an additional button attached to the notification. On an Android wearable, the action appears as a large button when the user swipes the notification to the left. When the user taps the action, the associated Intent is invoked on the handheld device.

Tip: If your notifications includes 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 Receiving Voice Input from a Notification.

For details about designing action buttons (including the icon specifications), see the Design Principles of Android Wear.

Add a Big View

You can insert extended text content to your notification by adding one of the "big view" styles to your notification. On a handheld device, users can see the big view content by expanding the notification, while on Android Wear, the big view content is visible by default.

To add the extended content to your notification, call setStyle() on the NotificationCompat.Builder object, passing it an instance of either BigTextStyle or InboxStyle.

For example, the following code adds an instance of NotificationCompat.BigTextStyle to the event notification, in order to include the complete event description (which includes more text than can fit into the space provided for setContentText()).

// Specify the 'big view' content to display the long
// event description that may not fit the normal content text.
BigTextStyle bigStyle = new NotificationCompat.BigTextStyle();
bigStyle.bigText(eventDescription);

NotificationCompat.Builder notificationBuilder =
        new NotificationCompat.Builder(this)
        .setSmallIcon(R.drawable.ic_event)
        .setLargeIcon(BitmapFractory.decodeResource(
                getResources(), R.drawable.notif_background))
        .setContentTitle(eventTitle)
        .setContentText(eventLocation)
        .setContentIntent(viewPendingIntent)
        .addAction(R.drawable.ic_map,
                getString(R.string.map), mapPendingIntent)
        .setStyle(bigStyle);

Notice that you can add a large background image to any notification using the setLargeIcon() method. For more information about designing notifications with large images, see the Design Principles of Android Wear.

Add New Features for Wearables

The Android Wear preview support library provides new APIs that allow you to enhance the user experience for notifications on a wearable device. For example, you can add additional pages of content that users can view by swiping to the left, or add the ability for users to deliver your app a text response using voice input.

To use these new APIs:

  1. Create an instance of NotificationCompat.Builder, setting the desired properties for your notification.
  2. Create a WearableNotificationOptions.Builder, setting the wearable-specific options for the notication.
  3. Call WearableNotificationOptions.Builder.applyTo() , passing in the NotificationCompat.Builder. This applies the wearable options to the notification.

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

// Create a NotificationCompat.Builder for standard notification features
 NotificationCompat.Builder builder = new NotificationCompat.Builder(mContext)
         .setContentTitle("New mail from " + sender)
         .setContentText(subject)
         .setSmallIcon(R.drawable.new_mail);
// Create a WearablesNotificationOptions.Builder to add functionality for wearables
 Notification notif = new WearableNotificationOptions.Builder()
         .setHintHideIcon(true)
         .build()
         .applyTo(builder); //apply wearable options to to the original notification
         .build()

The setHintHideIcon() method is just one example of new notification features available with the WearableNotificationOptions.Builder class.

When you want to deliver your notifications, always use the NotificationManagerCompat API instead of NotificationManager:

// Get an instance of the NotificationManager service
NotificationManagerCompat notificationManager =
        NotificationManagerCompat.from(this);

// Issue the notification with notification manager.
notificationManager.notify(notificationId, notif);

If you use the framework's NotificationManager, some features from WearableNotificationOptions.Builder do not work.

To continue enhancing your notifications for wearables using WearableNotificationOptions.Builder and other APIs in the preview support library, see the following developer guides:

Receiving Voice Input from a Notification
Add an action that receives voice input from the user and delivers the transcribed message to your app.
Adding Pages to a Notification
Add additional pages of information that are visible when the user swipes to the left.
Stacking Notifications
Place all similar notifications from your app in a stack, allowing each to be viewed individually without adding multiple cards to the card stream.

You might also want to read:

Notifying the User
Learn more about how to create notifications.
Intents and Intent Filters
Learn everything you need to know about the Intent APIs, used by notificaton actions.