WatchFacePushManager

Artifact: androidx.wear.watchfacepush:watchfacepush

Kotlin |Java

public interface 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 = WatchFacePushManagerFactory.createWatchFacePushManager(context)
with(wfp) {
    val slot = addWatchFace(wf1, token1)
    setWatchFaceAsActive(slot.slotId)
    updateWatchFace(slot.slotId, wf2, token2)
    removeWatchFace(slot.slotId)
}

Summary

Nested types
`public final class WatchFacePushManager.AddWatchFaceException extends Exception` An exception that can be thrown by `addWatchFace`
`public final class WatchFacePushManager.IsWatchFaceActiveException extends Exception` An exception that can be thrown by `isWatchFaceActive`
`public final class WatchFacePushManager.ListWatchFacesException extends Exception` An exception that can be thrown by `listWatchFaces`
`public final class WatchFacePushManager.ListWatchFacesResponse` Represents the response from listing watch faces.
`public final class WatchFacePushManager.RemoveWatchFaceException extends Exception` An exception that can be thrown by `removeWatchFace`
`public final class WatchFacePushManager.SetWatchFaceAsActiveException extends Exception` An exception that can be thrown by `setWatchFaceAsActive`
`public final class WatchFacePushManager.UpdateWatchFaceException extends Exception` An exception that can be thrown by `updateWatchFace`
`public final class WatchFacePushManager.WatchFaceDetails` Details about a watch face that is installed through this API.

Public methods
`abstract @NonNull WatchFacePushManager.WatchFaceDetails`	`addWatchFace( @NonNull ParcelFileDescriptor apkFd, @NonNull String validationToken )` Adds a new watch face.
`abstract boolean`	`isWatchFaceActive(@NonNull String watchfacePackageName)` Checks if a watch face with the given package name is active.
`abstract @NonNull WatchFacePushManager.ListWatchFacesResponse`	`listWatchFaces()` Lists all watch faces that were added by the app invoking this method.
`abstract void`	`removeWatchFace(@NonNull String slotId)` Removes an existing watch face that was previously added by this application.
`abstract void`	`setWatchFaceAsActive(@NonNull String slotId)` Sets a watch face with the given slot ID as the active watch face.
`abstract @NonNull WatchFacePushManager.WatchFaceDetails`	`updateWatchFace( @NonNull String slotId, @NonNull ParcelFileDescriptor apkFd, @NonNull String validationToken )` Updates a watch face slot with a new watch face.

Public methods

addWatchFace

abstract @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.watchfacepush.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

abstract 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.watchfacepush.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

abstract @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.watchfacepush.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.0.0-alpha01

abstract 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.watchfacepush.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.0.0-alpha01

abstract 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.watchfacepush.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

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

Updates a watch face slot with a new watch face. Watch faces added by other apps or already existing on the device cannot be updated using this method. The new watch face could be a newer version of the existing watch face or a completely different watch face. If the slot is updated with a watch face that has the same package name as the existing watch face, all the associated user configuration settings of the watch face will be preserved. If the package name is different, the user configuration settings will be reset to the default values.

Parameters
`@NonNull String slotId`	The slot ID to update.
`@NonNull ParcelFileDescriptor apkFd`	The `ParcelFileDescriptor` containing the new 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.watchfacepush.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.

WatchFacePushManager

Summary

Nested types

Public methods

Public methods

addWatchFace

isWatchFaceActive

listWatchFaces

removeWatchFace

setWatchFaceAsActive

updateWatchFace