Skip to content

Most visited

Recently visited


Building a Watch Face Service

Android Wear watch faces are services that are packaged inside a wearable app. When users select one of the available watch faces, the wearable device shows the watch face and invokes its service callback methods.

When you install a wearable app with watch faces, the watch faces become available in the watch face picker on the wearable. If you'd like to select the watch faces from your phone, you must install the watch's companion app from the Google Play Store, if one is available.

This lesson shows you how to configure an Android project to include watch faces and how to implement the watch face service.

Create and configure your project

To create an Android project for your watch face in Android Studio:

  1. Click File > New Project and follow the steps in the Create New Project wizard until you reach the Target Android Devices page.
  2. Select the Wear option, and in the Minimum SDK option list, select the latest available (API Nougat) option. Click Next.
  3. Select Add No Activity and click Next in the two following screens.
  4. Click Finish.

Android Studio creates a project with a wear module. For more information, see Creating a Project.


The Wearable Support Library provides the necessary classes that you extend to create watch face implementations. The Google Play services client libraries (play-services and play-services-wearable) are required to sync data items between the companion device and the wearable with the Wearable Data Layer API.

Android Studio automatically adds the required entries in your build.gradle files when you create the project in the instructions above.

Wearable support library API reference

The reference documentation provides detailed information about the classes you use to implement watch faces. Browse the API reference documentation for the Wearable Support Library.

Note: We recommend using Android Studio for Android Wear development, as it provides project setup, library inclusion, and packaging conveniences.

Declare permissions

A watch face requires the WAKE_LOCK permission. Add the following permission to the manifest files of both the wearable app and the mobile app under the manifest element:

<manifest ...>
        android:name="android.permission.WAKE_LOCK" />

    <!-- Required for complications to receive complication data and open the provider chooser. -->

Caution: The handheld app must include all of the permissions declared in the wearable app.

Implement the service and callback methods

Watch faces in Android Wear are implemented as services. When a watch face is active, the system invokes the methods in its service when the time changes or when an important event occurs (like switching to ambient mode or receiving a new notification). The service implementation then draws the watch face on the screen using the updated time and any other relevant data.

To implement a watch face, you extend the CanvasWatchFaceService and CanvasWatchFaceService.Engine classes, and then you override the callback methods in the CanvasWatchFaceService.Engine class. These classes are included in the Wearable Support Library.

The following snippet outlines the key methods you need to implement:

public class AnalogWatchFaceService extends CanvasWatchFaceService {

    public Engine onCreateEngine() {
        /* provide your watch face implementation */
        return new Engine();

    /* implement service callback methods */
    private class Engine extends CanvasWatchFaceService.Engine {

        public void onCreate(SurfaceHolder holder) {
            /* initialize your watch face */

        public void onPropertiesChanged(Bundle properties) {
            /* get device features (burn-in, low-bit ambient) */

        public void onTimeTick() {
            /* the time changed */

        public void onAmbientModeChanged(boolean inAmbientMode) {
            /* the wearable switched between modes */

        public void onDraw(Canvas canvas, Rect bounds) {
            /* draw your watch face */

        public void onVisibilityChanged(boolean visible) {
            /* the watch face became visible or invisible */

The CanvasWatchFaceService class provides an invalidate mechanism similar to the View.invalidate() method. You can call the invalidate() method throughout your implementation when you want the system to redraw the watch face. You can only use the invalidate() method in the main UI thread. To invalidate the canvas from another thread, call the postInvalidate() method.

For more information about implementing the methods in the CanvasWatchFaceService.Engine class, see Drawing Watch Faces.

Register the watch face service

After you implement the watch face service, you register the implementation in the manifest file of the wearable app. When users install this app, the system uses the information about the service to make the watch face available in the Android Wear companion app and in the watch face picker on the wearable device.

The following snippet shows how to register a watch face implementation under the application element:

    android:permission="android.permission.BIND_WALLPAPER" >
        android:resource="@xml/watch_face" />
        android:resource="@drawable/preview_analog" />
        android:resource="@drawable/preview_analog_circular" />
        <action android:name="android.service.wallpaper.WallpaperService" />
            "" />

The Android Wear companion app and the watch face picker on the wearable device use the preview image defined by the metadata entry when presenting users with all the watch faces installed on the device. To obtain this drawable, run the watch face on your Android Wear device or in an emulator instance and take a screenshot. On Android Wear devices with hdpi screens, the preview image is typically 320x320 pixels in size.

Watch faces that look substantially different on round devices can provide both round and square preview images. To specify a round preview image, use the metadata entry. If a watch face includes both preview images, the companion app and the watch face picker on the wearable show the appropriate one, depending on the shape of the watch. If a round preview image is not included, the square preview image is used for both square and round devices. For round devices, a square preview image is cropped using a circular shape.

The android.service.wallpaper metadata entry specifies the watch_face.xml resource file, which contains a wallpaper element:

<?xml version="1.0" encoding="UTF-8"?>
<wallpaper xmlns:android="" />

Your wearable app can contain more than one watch face. You must add a service entry to the manifest file of the wearable app for each of your watch face implementations.

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


WeChat에서 Google Developers 팔로우하기

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. (Dec 2017 Android Platform & Tools Survey)