WatchFacePushManager

public final 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 methods
final @NonNull WatchFacePushManager.WatchFaceDetails
addWatchFace(
    @NonNull ParcelFileDescriptor apkFd,
    @NonNull String validationToken
)

Adds a new watch face.
final boolean
isWatchFaceActive(@NonNull String watchfacePackageName)

Checks if a watch face with the given package name is active.
final @NonNull WatchFacePushManager.ListWatchFacesResponse

Lists all watch faces that were added by the app invoking this method.
final void

Removes an existing watch face that was previously added by this application.
final void

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

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

Public constructors

WatchFacePushManager

Added in 1.3.0-alpha07
public WatchFacePushManager(@NonNull Context context)
Parameters
@NonNull Context context

The application context.

Public methods

addWatchFace

public final @NonNull WatchFacePushManager.WatchFaceDetails addWatchFace(
    @NonNull ParcelFileDescriptor apkFd,
    @NonNull String validationToken
)

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
@NonNull ParcelFileDescriptor apkFd

The ParcelFileDescriptor containing the watch face APK.
@NonNull String validationToken

A token proving that the watch face has gone through the required validation checks.
Returns
@NonNull 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

public final boolean isWatchFaceActive(@NonNull String watchfacePackageName)

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
@NonNull String watchfacePackageName

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

public final @NonNull WatchFacePushManager.ListWatchFacesResponse listWatchFaces()

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
@NonNull 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
public final void removeWatchFace(@NonNull String slotId)

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
@NonNull String slotId

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
public final void setWatchFaceAsActive(@NonNull String slotId)

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
@NonNull String slotId

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

public final @NonNull WatchFacePushManager.WatchFaceDetails updateWatchFace(
    @NonNull String slotId,
    @NonNull ParcelFileDescriptor apkFd,
    @NonNull String validationToken
)

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
@NonNull String slotId

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

The ParcelFileDescriptor containing the updated watch face APK.
@NonNull String validationToken

A token proving that the watch face has gone through the required validation checks.
Returns
@NonNull 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.