blob: 6f8497a21ec40db814d0ef5990873869021689ca [file] [log] [blame]
page.title=Creating a Notification for Wearables
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson teaches you to</h2>
<li><a href="#Import">Import the Necessary Classes</a></li>
<li><a href="#NotificationBuilder">Create Notifications with the Notification Builder</a></li>
<li><a href="#ActionButtons">Add Action Buttons</a></li>
<li><a href="#SpecifyWearableOnlyActions">Specify Wearable-only Actions</a></li>
<li><a href="#BigView">Add a Big View</a></li>
<li><a href="#AddWearableFeatures">Add Wearable Features for a Notification</a></li>
<li><a href="#Deliver">Deliver the Notification</a></li>
<p>To build handheld notifications that are also sent to wearables, use
{@link}. When you build
notifications with this class, the system takes care of displaying
notifications properly, whether they appear on a handheld or wearable.
<p class="note"><strong>Note:</strong>
Notifications using {@link android.widget.RemoteViews} are stripped of custom
layouts and the wearable only displays the text and icons. However, you can create
<a href="{@docRoot}training/wearables/apps/layouts.html#CustomNotifications">create custom notifications</a>
that use custom card layouts by creating a wearable app that runs on the wearable device.</p>
<h2 id="Import">Import the necessary classes</h2>
<p>To import the necessary packages, add this line to your <code>build.gradle</code>file:</p>
compile ""
<p>Now that your project has access to the necessary packages, import the necessary classes from
the support library:</p>
<pre style="clear:right">
<h2 id="NotificationBuilder">Create Notifications with the Notification Builder</h2>
<p>The <a href="">v4
support library</a> 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.</p>
<p>To create a notification with the support library, you create an instance of
{@link} and issue the notification by
passing it to {@link notify()}. For example:
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)
// Get an instance of the NotificationManager service
NotificationManagerCompat notificationManager =
// Build the notification and issues it with notification manager.
<p>When this notification appears on a handheld device, the user can invoke the
specified by the {@link
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 <strong>Open</strong> action, which invokes the intent on the handheld device.</p>
<img src="{@docRoot}wear/images/circle_email_action.png" height="200"
style="float:right;clear:right;margin:0 0 20px 60px" />
<h2 id="ActionButtons">Add Action Buttons</h2>
<p>In addition to the primary content action defined by
setContentIntent()}, you can add other actions by passing a {@link} to
the {@link addAction()} method.</p>
<p>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.</p>
<pre style="clear:right">
// 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));
PendingIntent mapPendingIntent =
PendingIntent.getActivity(this, 0, mapIntent, 0);
NotificationCompat.Builder notificationBuilder =
new NotificationCompat.Builder(this)
getString(, mapPendingIntent);</b>
<p>On a handheld, the action appears as an
additional button attached to the notification. On a 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.</p>
<p class="note"><strong>Tip:</strong> 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
<a href="{@docRoot}training/wearables/notifications/voice-input.html">Receiving Voice Input from
a Notification</a>.
<h2 id="SpecifyWearableOnlyActions">Specify Wearable-only Actions</h2>
If you want the actions available on the wearable to be different from those on the handheld,
then use {@link WearableExtender.addAction()}.
Once you add an action with this method, the wearable does not display any other actions added with
{@link NotificationCompat.Builder.addAction()}.
That is, only the actions added with {@link WearableExtender.addAction()} appear on the wearable and they do not appear on the handheld.
// Create an intent for the reply action
Intent actionIntent = new Intent(this, ActionActivity.class);
PendingIntent actionPendingIntent =
PendingIntent.getActivity(this, 0, actionIntent,
// Create the action
NotificationCompat.Action action =
new NotificationCompat.Action.Builder(R.drawable.ic_action,
getString(R.string.label), actionPendingIntent)
// Build the notification and add the action via WearableExtender
Notification notification =
new NotificationCompat.Builder(mContext)
.extend(new WearableExtender().addAction(action))
<h2 id="BigView">Add a Big View</h2>
<img src="{@docRoot}wear/images/06_images.png" height="200"
style="float:right;margin:0 0 20px 40px" />
<p>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. On
a wearable device, the big view content is visible by default.</p>
<p>To add the extended content to your notification, call {@link setStyle()} on the {@link} object, passing it an instance of either
{@link BigTextStyle} or
{@link InboxStyle}.</p>
<p>For example, the following code adds an instance of
{@link} to the event notification,
in order to include the complete event description (which includes more text than can fit
into the space provided for {@link
<pre style="clear:right">
// Specify the 'big view' content to display the long
// event description that may not fit the normal content text.
BigTextStyle bigStyle = new NotificationCompat.BigTextStyle();
NotificationCompat.Builder notificationBuilder =
new NotificationCompat.Builder(this)
getResources(), R.drawable.notif_background))
getString(, mapPendingIntent)
<p>Notice that you can add a large icon image to any notification using the
{@link setLargeIcon()}
method. However, these icons appear as large background images on a wearable and do not look
good as they are scaled up to fit the wearable screen. To add a wearable-specific background image
to a notification, see <a href="#AddWearableFeatures">Add Wearable Features For a Notification</a>.
For more information about designing notifications with large images, see the
<a href="{@docRoot}design/wear/index.html">Design Principles of Android
<h2 id="AddWearableFeatures">Add Wearable Features For a Notification</h2>
<p>If you ever need to add wearable-specific options to a notification, such as specifying additional
pages of content or letting users dictate a text response with voice input, you can use the
{@link} class to
specify the options. To use this API:</p>
<li>Create an instance of a {@link WearableExtender},
setting the wearable-specific options for the notication.</li>
<li>Create an instance of
{@link}, setting the
desired properties for your notification as described earlier in this lesson.</li>
<li>Call {@link extend()} on
the notification and pass in the
{@link WearableExtender}. This applies
the wearable options to the notification.</li>
<li>Call {@link} to build the notification.</li>
For example, the following code calls the
{@link 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()
// 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)
{@link setHintHideIcon()}
and {@link setBackground()}
methods are just two examples of new notification features available with
<p class="note"><strong>Note:</strong> The bitmap that you use with
{@link setBackground()}
should have a resolution of 400x400 for non-scrolling backgrounds and 640x400 for backgrounds
that support parallax scrolling. Place these bitmap images in the <code>res/drawable-nodpi</code>
directory. Place other non-bitmap resources for wearable notifications, such
as those used with the
{@link setContentIcon()}
method, in the <code>res/drawable-hdpi</code> directory.</p>
<p>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
{@link} method to
get whether or not this notification hides the icon:</p>
NotificationCompat.WearableExtender wearableExtender =
new NotificationCompat.WearableExtender(notif);
boolean hintHideIcon = wearableExtender.getHintHideIcon();
<h2 id="Deliver">Deliver the Notification</h2>
<p>When you want to deliver your notifications, always use the
{@link} API instead of
// Get an instance of the NotificationManager service
NotificationManagerCompat notificationManager =
// Issue the notification with notification manager.
notificationManager.notify(notificationId, notif);
<p>If you use the framework's {@link}, some
features from {@link}
do not work, so make sure to use {@link}.