Stay organized with collections
Save and categorize content based on your preferences.
For the canonical marketplace, the phone app is the predominant way in which
the user interacts with the app.
Set a watch face
When the user selects a watch face in the phone app, there are two parts to the
subsequent flow to set the watch face:
Installation: Install the watch face using Watch Face Push, initiated
through MessageClient. This step is straightforward, using either
addWatchFace or updateWatchFace, triggered using MessageClient from
the phone to the watch.
There may be no action needed. The marketplace may already have
control of the active watch face.
There may be no user intervention needed. The app has the necessary
permissions to set the active watch face, and can do so directly using
setWatchFaceAsActive().
There may be guidance needed, either as to how to accept permission
requests, or how to manually set the watch face using a long-press
gesture or through a companion app.
Installation response
To facilitate the Activation phase, the Installation phase should return
the following information from the watch to the phone:
The outcome of the installation attempt
The result of isWatchFaceActive() - to determine whether the app already
has the active watch face.
Whether setWatchFaceAsActive() has already been called in the past - the
Wear OS app should track and persist this information locally. This API
call can only be used once.
Activation
Following the installation, the response may indicate that the app already has
the active watch face. However if it does not, then the app may choose to show a
button to set watch face as active.
Scenario 1: All attempts to set the active watch face are exhausted
If the response from installation indicated that setWatchFaceAsActive() had
already been called in the past, then the button should lead to an education
screen on the phone, showing the user how to touch & hold on the watch face to
manually set it to the one they want.
Scenario 2 - Try to set the active watch face
The phone should instruct the watch to check for the necessary
SET_PUSHED_WATCH_FACE_AS_ACTIVE permission:
If the user has already granted it, proceed to calling
setWatchFaceAsActive().
If the user has previously denied the permission, the watch should
communicate this back to the phone, where an education screen can be shown
explaining the need for the permission and how to manually grant it.
If the permission has not been requested before, the watch should
instruct the phone to show an educational moment guiding the user on how to
accept permissions on the watch, and the watch should proceed to request the
permission.
If the user grants the permission, the watch should then call
setWatchFaceAsActive().
Otherwise the watch should instruct the phone to show an education
screen explaining the need for the permission and how to manually grant
it.
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2025-08-29 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-29 UTC."],[],[],null,["# Configure your phone app for Watch Face Push\n\nFor the canonical marketplace, the phone app is the predominant way in which\nthe user interacts with the app.\n\nSet a watch face\n----------------\n\nWhen the user selects a watch face in the phone app, there are two parts to the\nsubsequent flow to set the watch face:\n\n1. **Installation:** Install the watch face using Watch Face Push, initiated through `MessageClient`. This step is straightforward, using either `addWatchFace` or `updateWatchFace`, triggered using `MessageClient` from the phone to the watch.\n2. **Activation:** [Set the installed watch face as active](/training/wearables/watch-face-push/wear-os-app#set-watch-face-as-active). This step has several possible paths, depending on the permission state:\n - There may be **no action needed**. The marketplace may already have control of the active watch face.\n - There may be **no user intervention needed** . The app has the necessary permissions to set the active watch face, and can do so directly using `setWatchFaceAsActive()`.\n - There may be **guidance needed**, either as to how to accept permission requests, or how to manually set the watch face using a long-press gesture or through a companion app.\n\nInstallation response\n---------------------\n\nTo facilitate the **Activation** phase, the **Installation** phase should return\nthe following information from the watch to the phone:\n\n- The outcome of the installation attempt\n- The result of `isWatchFaceActive()` - to determine whether the app already has the active watch face.\n- Whether `setWatchFaceAsActive()` has already been called in the past - the Wear OS app should track and persist this information locally. *This API\n call can only be used once.*\n\nActivation\n----------\n\nFollowing the installation, the response may indicate that the app already has\nthe active watch face. However if it does not, then the app may choose to show a\nbutton to **set watch face as active**.\n\n### Scenario 1: All attempts to set the active watch face are exhausted\n\nIf the response from installation indicated that `setWatchFaceAsActive()` had\nalready been called in the past, then the button should lead to an education\nscreen on the phone, showing the user how to touch \\& hold on the watch face to\nmanually set it to the one they want.\n\n### Scenario 2 - Try to set the active watch face\n\nThe phone should instruct the watch to check for the necessary\n`SET_PUSHED_WATCH_FACE_AS_ACTIVE` permission:\n\n- If the user has **already granted it**, proceed to calling setWatchFaceAsActive().\n- If the user has **previously denied the permission**, the watch should communicate this back to the phone, where an education screen can be shown explaining the need for the permission and how to manually grant it.\n- If the **permission has not been requested before**, the watch should\n instruct the phone to show an educational moment guiding the user on how to\n accept permissions on the watch, and the watch should proceed to request the\n permission.\n\n - If the user grants the permission, the watch should then call `setWatchFaceAsActive()`.\n - Otherwise the watch should instruct the phone to show an education screen explaining the need for the permission and how to manually grant it."]]
