Provide configuration activities on Wear OS

Some watch faces support configuration parameters to let users customize how the watch face looks and behaves. For example, some watch faces let users pick a custom background color. Other watch faces that tell time for two different time zones allow users to select which time zones they are interested in.

Watch faces that support configuration parameters allow users to customize a watch face using an activity. Users can start the wearable configuration activity on the wearable device. They can also start the companion configuration activity from the handheld app, if it has been installed. Additionally, users can configure the watch face in the device companion app for Wear OS 3 devices.

Note:Configuration on the device companion app is available on devices that target API level 30 and higher. Configuration on a handheld app is available on all devices.

Use editor session

We strongly recommend that you allow supporting configuration on the smartwatch so that the user can customize their watch face without requiring a companion device.

To support this, a watch face can provide a configuration Activity and allow the user to change settings using an EditorSession returned from EditorSession.createOnWatchEditorSession. As the user makes changes, calling EditorSession.renderWatchFaceToBitmap provides a live preview of the watch face in the editor Activity.

Specify an intent for configuration activities

If your watch face includes configuration activities, and you are configuring your watch face from the device companion app, add the following metadata entries to the service declaration in the manifest file of the wearable app:

<service>
    <meta-data
        android:name="com.google.android.wearable.watchface.wearableConfigurationAction"
        android:value="androidx.wear.watchface.editor.action.WATCH_FACE_EDITOR" />
    <meta-data
        android:name="com.google.android.wearable.watchface.companionBuiltinConfigurationEnabled"
        android:value="true" />
</service>

Configuration activities register intent filters for this intent, and the system fires this intent when users want to configure your watch face.

If your watch face only includes a companion or a wearable configuration activity, you only need to include the corresponding metadata entry from the example above.

Create a wearable configuration activity

Wearable configuration activities provide a limited set of customization choices for a watch face, because complex menus are hard to navigate on smaller screens. Your wearable configuration activity should provide binary choices and just a few selections to customize the main aspects of your watch face.

To create a wearable configuration activity, add a new activity to your wearable app module and declare the following intent filter in the manifest file of the wearable app:

<activity
    android:name=".DigitalWatchFaceWearableConfigActivity"
    android:label="@string/digital_config_name">
    <intent-filter>
        <action android:name="androidx.wear.watchface.editor.action.WATCH_FACE_EDITOR" />
        <category android:name=
        "com.google.android.wearable.watchface.category.WEARABLE_CONFIGURATION" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

The name of the action in this intent filter must be androidx.wear.watchface.editor.action.WATCH_FACE_EDITOR.

In your configuration activity, build a simple UI that provides selections for users to customize your watch face. For more information see Use editor session.

Refer to the following related resources: