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, and
watch faces that tell time for two different time zones can let users select which time zones
they are interested in.

Watch faces that support configuration parameters can let users customize a watch face using
an activity in the wearable app, an activity on the handheld app, or both. 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.

Note:
In Wear 1.x, when the user installs a handheld app
that contains a wearable app, the wearable app is automatically installed on the watch.
In Wear 2.0, a wearable app is never automatically installed on the watch.
Furthermore, in Wear 2.0 a handheld app is not required. If one exists and you'd like to
use it, you must install it separately.

The digital watch face from the
WatchFace sample demonstrates how to
implement handheld and wearable configuration activities and how to update a watch face in
response to configuration changes.

Specify an intent for configuration activities

If your watch face includes configuration activities, add the following metadata entries to
the service declaration in the manifest file of the wearable app:

Provide values for these entries that are preceded by the package name of your app.
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:

In your configuration activity, build a simple UI that provides selections for users to
customize your watch face. When users make a selection, use the Wearable Data Layer API to
communicate the configuration change to the watch face activity.

For more details, see the DigitalWatchFaceWearableConfigActivity and
DigitalWatchFaceUtil classes in the
WatchFace sample.

Create a companion configuration activity

Companion configuration activities give users access to the full set of configuration choices
for a watch face, because it is easier to interact with complex menus on the larger screen of
a handheld device. For example, a configuration activity on a handheld device enables you to
present users with elaborate color pickers to select the background color of a watch face.

Note: Configuration activities can only be written for handheld
devices running Android.

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

In your configuration activity, build a UI that provides options to customize all the
configurable elements of your watch face. When users make a selection, use the Wearable Data Layer API to
communicate the configuration change to the watch face activity.

For more details, see the DigitalWatchFaceCompanionConfigActivity class in the
WatchFace sample.

Create a listener service in the wearable app

To receive updated configuration parameters from the configuration activities, create a
service that implements the
WearableListenerService
interface from the
Wearable Data Layer API in your
wearable app. Your watch face implementation can redraw the watch face when the configuration
parameters change.

For more details, see the DigitalWatchFaceConfigListenerService and
DigitalWatchFaceService classes in the
WatchFace sample.