Watchface Project Configuration


To create an Android™ watchface, you need to create a wearable app and a handheld app. The wearable app contains one or more watchfaces and optionally a configuration screen. The handheld app is necessary, because users can't install an app directly on their smartwatch, but instead they install an app on their phone, which will automatically install the bundled wearable app onto the paired watch.

This tutorial will teach you how to configure an Android Studio project for watchfaces.

Create Your Project

To create an Android Studio project for your watchface, follow these steps:

  • Start Android Studio
  • Create a new project ("Start a new Android Studio project")
    • Choose a name (like SampleWatch)
    • Enter a Company Name
      • The package name is created from those two names
      • The domain and the project name SampleWatch will result in the package name com.example.wearable.samplewatch
    • If necessary, you can change the save location of your project
  • Click Next
    • Select "Phone and Tablet"
      • Android Wear is available at API Version 18, so the minimum SDK Level must be 18
    • Select Wear
      • Here you need API Level 21, because the watchface API was added in this version
  • Click on Next
    • For the mobile app, choose "Add No Activity"
  • Click Next
    • For the wearable app, choose "Add No Activity"
  • Click on Finish

Now you have to wait a few seconds, while the project is generated.

Declare Permissions

Every watchface needs the PROVIDE_BACKGROUND and the WAKE_LOCK permission. To declare them, we need to add them to the manifest.

All permissions of the wearable app must be stored also in the handheld app!

You find the files in the corresponding subfolder manifests and is called AndroidManifest.xml
The following lines must be added to both manifests inside the manifest-tag:

<uses-permission android:name="" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

The AndroidManifest.xml file should now look something like this:

<manifest xmlns:android=""

    <uses-permission android:name="" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />

    <uses-feature android:name="" />
    <application android:allowBackup="true" android:label="@string/app_name"
       android:icon="@drawable/ic_launcher" android:theme="@android:style/Theme.DeviceDefault">


Watchface Implementation

To actually implement a new watchface, you have to create a new class. It must extend CanvasWatchFaceService and the onCreateEngine method should return a new Engine.

public class SampleWatchfaceService extends CanvasWatchFaceService {
    public Engine onCreateEngine() {
        return new Engine();

    private class Engine extends CanvasWatchFaceService.Engine {
        public void onCreate(SurfaceHolder holder) {
            // initialize watchface
            // like load images, create Paint objects ...

        public void onPropertiesChanged(Bundle properties) {
            // get device features
            // like burn-in protection and low-bit ambientmode

        public void onTimeTick() {
            // Time changed
            // force a redraw

        public void onAmbientModeChanged(boolean inAmbientMode) {
            // change mode

        public void onDraw(Canvas canvas, Rect bounds) {
            // Draw watch

        public void onVisibilityChanged(boolean visible) {
            // Watch became (in)visible

You find an example implementation in my following post: Watchface implementation.

Whenever anything changed, like the timezone or the actually time, you should redraw the watchface. The easiest way to do this, is to call the invalidate method.

Register Watchface Service

The watchface is shown in the companion app, only if you registered it as a service in the manifest file. To do so, we open the AndroidManifest.xml file of our wearable app and add the following code to the application tag:

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

Some entries are marked red, because they refer to some not existing files. First of all we create the missing xml file. We should put it into the xml folder, which we should create as follows:

Now we create a new file inside this directory. Rightclick on the directory -> New -> File. The name should match the name mentioned in the manifest file. In our case this is watch_face.xml. Click OK and copy the following code into the file:

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

Now only two red marks are left. The marked lines are used to refer to the preview images of our watchface.
The resource string tells us, that the images (preview and preview_circular) are inside the drawable directory.

Move or copy the images into drawable directory. They should have the following size: 320*320
As long as your watchface is not complete, you can use the following images:

In case your cicular watchface looks just like the square version, you can remove the meta-data entry of your circular image (preview_circular).

When your watchface is ready, you can replace the images with actual screenshots of your watch.

The companion app can make screenshots of your wearable. To do so, tap on the menu button on top right and choose Take wearable screenshot.

Compile And Run

Now we're ready to test our watchface. First of all we need to define the correct build-type. Because we don't want to run our mobile app, but the wearable app, we need to choose it:

Then we can hit the play button. After that a new dialog should open and we can enter some configuration details. Normally android studio wants to run the Default Activity. But we're developing a watchface, so there is no default activity. Just check "Do not launch Activity" and click on Run.
Now the project is compiled and after a short time we see a dialog to choose our wearable device. In the case you want to run it inside an emulator, you can start one with a click on "Launch Emulator".
After you selected the correct device, the app is installed on the device. This may take some seconds and after that we can select the new watchface and praise it.
But because we don't implemented the actual drawing, we only see a black screen.

Congratulations! We created our first watchface!

As you can see, it is not so hard to create and configure a watchface project. If you have any questions or remarks, just leave a comment.