Custom watch face for Android Wear

Question

A few apps have come out already for Android Wear that contain custom watch faces (like this one). They are not just apps that simply display a watch face; they are full-fledged faces that are selectable when long-pressing the home screen of the watch. I can't find any documentation on how to set up your app to provide a custom face. How do you configure your app to provide a face?

Answer 1

EDIT With the update of Android Wear to Lollipop, there is a brand-new (and more importantly, official) API for Android Wear Watch Faces.

You can check the blog post on the subject, read the official documentation or download the sample code.

Everything below this line is for historical purposes only :)

---

You just need to provide an Activity with a specific intent-filter, and include a couple of permissions (information from here).

Activity:

<activity
    android:name=".WatchActivity"
    android:allowEmbedded="true"
    android:theme="@android:style/Theme.DeviceDefault.NoActionBar"
    android:label="@string/watch_preview_name">

    <meta-data
        android:name="com.google.android.clockwork.home.preview"
        android:resource="@drawable/watch_preview_image" />

    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="com.google.android.clockwork.home.category.HOME_BACKGROUND" />
    </intent-filter>
</activity>

And the permissions:

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

By the way, the source code from the app you mentioned from the Play Store is also availabe on github.

---

The reason for including the WAKE_LOCK permission is very well explained in this G+ post by Sam Duke. Basically, when the watch is dimmed the CPU goes into a low power state, so that updates to the watch face display aren't shown immediately. Acquiring a PARTIAL_WAKE_LOCK whenever the screen needs to be updated solves this problem.

---

EDIT Note that this is an "unofficial" API, and as per this post by Wayne Piekarski, it may break in the future when the official API is released (which should happen when Android Wear is upgraded to L).

Answer 2

EDIT: Below is a new blog post of mine that explains the new Watch Face API in Lollipop.

http://toastdroid.com/2014/12/10/developing-a-watch-face-for-android-wear-lollipop/

---

I wrote a blog post describing the process of developing a watchface.

http://toastdroid.com/2014/07/18/developing-watchfaces-for-android-wear/