WatchFacePushManager

class WatchFacePushManager

The Watch Face Push API allows a Wear OS app to install a watch face on a watch programmatically. The watch faces will then be available in the watch carousel similarly to watch faces that are downloaded from Play Store. It's important to note that all functions in this API operate only on watch faces that have been added by the calling application. Watch faces added by other apps or pre-existing on the device cannot be managed using this API.

Example usage:

lateinit var wf1: android.os.ParcelFileDescriptor
val token1 = "1234" // Get it from the provided validation library.
lateinit var wf2: android.os.ParcelFileDescriptor
val token2 = "4567"
val wfp = WatchFacePushManager(context)
with(wfp) {
    val slot = addWatchFace(wf1, token1)
    setWatchFaceAsActive(slot.slotId)
    updateWatchFace(slot.slotId, wf2, token2)
    removeWatchFace(slot.slotId)
}

Summary

Nested types

An exception that can be thrown by addWatchFace

An exception that can be thrown by isWatchFaceActive

An exception that can be thrown by listWatchFaces

Represents the response from listing watch faces.

An exception that can be thrown by removeWatchFace

An exception that can be thrown by setWatchFaceAsActive

An exception that can be thrown by updateWatchFace

Details about a watch face that is installed through this API.

Public constructors

Public functions
suspend WatchFacePushManager.WatchFaceDetails
addWatchFace(apkFd: ParcelFileDescriptor, validationToken: String)

Adds a new watch face.
suspend Boolean
isWatchFaceActive(watchfacePackageName: String)

Checks if a watch face with the given package name is active.
suspend WatchFacePushManager.ListWatchFacesResponse

Lists all watch faces that were added by the app invoking this method.
suspend Unit

Removes an existing watch face that was previously added by this application.
suspend Unit

Sets a watch face with the given slot ID as the active watch face.
suspend WatchFacePushManager.WatchFaceDetails
updateWatchFace(
    slotId: String,
    apkFd: ParcelFileDescriptor,
    validationToken: String
)

Updates an existing watch face that was previously added by this app.

Public constructors

WatchFacePushManager

Added in 1.3.0-alpha07
WatchFacePushManager(context: Context)
Parameters
context: Context

The application context.

Public functions

addWatchFace

suspend fun addWatchFace(apkFd: ParcelFileDescriptor, validationToken: String): WatchFacePushManager.WatchFaceDetails

Adds a new watch face. On success, the given watch face will be available in the watch face carousel on the watch. Note that calling this method will not change the currently active watch face. See also setWatchFaceAsActive.

Parameters
apkFd: ParcelFileDescriptor

The ParcelFileDescriptor containing the watch face APK.
validationToken: String

A token proving that the watch face has gone through the required validation checks.
Returns
WatchFacePushManager.WatchFaceDetails

The WatchFaceDetails representing the added watch face in its assigned slot.
Throws
androidx.wear.watchface.push.WatchFacePushManager.AddWatchFaceException

if there is an error while adding the watch face. This could happen if the provided APK is malformed, the validation token is invalid, or if the Watch Face Push service on the watch cannot be accessed. See AddWatchFaceException.errorCode for the possible errors thrown by this method if the watch face cannot be added.

isWatchFaceActive

suspend fun isWatchFaceActive(watchfacePackageName: String): Boolean

Checks if a watch face with the given package name is active. This method can only be used to check the active status of watch faces installed by this application.

Parameters
watchfacePackageName: String

The package name of the watch face to check.
Returns
Boolean

true if the watch face is active, false otherwise.
Throws
androidx.wear.watchface.push.WatchFacePushManager.IsWatchFaceActiveException

if there is an error while checking if the watch face is active. This could happen if the provided watchfacePackageName is invalid or if the Watch Face Push service on the watch cannot be accessed. See IsWatchFaceActiveException.errorCode for details.

listWatchFaces

suspend fun listWatchFaces(): WatchFacePushManager.ListWatchFacesResponse

Lists all watch faces that were added by the app invoking this method. Watch faces added by other apps will not be included in the response.

Returns
WatchFacePushManager.ListWatchFacesResponse

A ListWatchFacesResponse containing the list of installed watch face details and the number of available slots for this application.
Throws
androidx.wear.watchface.push.WatchFacePushManager.ListWatchFacesException

if there is an error while retrieving the watch faces. This could happen if the Watch Face Push service on the watch cannot be accessed. See ListWatchFacesException.errorCode for details.

removeWatchFace

Added in 1.3.0-alpha07
suspend fun removeWatchFace(slotId: String): Unit

Removes an existing watch face that was previously added by this application. On success, the watch face will no longer be available in the watch face carousel on the watch. Note that this method can be used to remove the currently active watch face - in that case, the watch will revert to one of the other existing watch faces. Watch faces added by other apps or pre-existing on the device cannot be removed using this method.

Parameters
slotId: String

The unique identifier of the watch face to be removed. This ID corresponds to the WatchFaceDetails.slotId of the watch face.
Throws
androidx.wear.watchface.push.WatchFacePushManager.RemoveWatchFaceException

if there is an error while removing the watch face. This could happen if the provided slotId is invalid or if the Watch Face Push service on the watch cannot be accessed. See RemoveWatchFaceException.errorCode for details.
See also
addWatchFace

setWatchFaceAsActive

Added in 1.3.0-alpha07
suspend fun setWatchFaceAsActive(slotId: String): Unit

Sets a watch face with the given slot ID as the active watch face. This method can only be used to set watch faces installed by this application as active.

Parameters
slotId: String

The slot ID of the watch face to set as active.
Throws
androidx.wear.watchface.push.WatchFacePushManager.SetWatchFaceAsActiveException

if there is an error while setting the watch face as active. This could happen if the provided slotId is invalid, the maximum number of attempts to set the watch face as active has been reached, the required permission is missing, or if the Watch Face Push service on the watch cannot be accessed. See SetWatchFaceAsActiveException.errorCode for details.

updateWatchFace

suspend fun updateWatchFace(
    slotId: String,
    apkFd: ParcelFileDescriptor,
    validationToken: String
): WatchFacePushManager.WatchFaceDetails

Updates an existing watch face that was previously added by this app. Watch faces added by other apps or already existing on the device cannot be updated using this method.

Parameters
slotId: String

The slot ID of the watch face to update.
apkFd: ParcelFileDescriptor

The ParcelFileDescriptor containing the updated watch face APK.
validationToken: String

A token proving that the watch face has gone through the required validation checks.
Returns
WatchFacePushManager.WatchFaceDetails

The WatchFaceDetails representing the updated watch face in the specified slot.
Throws
androidx.wear.watchface.push.WatchFacePushManager.UpdateWatchFaceException

if there is an error while updating the watch face. This could happen if the provided APK is malformed, the validation token is invalid, or if the Watch Face Push service on the watch cannot be accessed. See UpdateWatchFaceException.errorCode for the possible errors thrown by this method if the watch face cannot be updated.