# WatchFacePushManager

Artifact: [androidx.wear.watchfacepush:watchfacepush](https://developer.android.com/jetpack/androidx/releases/wear-watchfacepush) [View Source](https://cs.android.com/search?q=file:androidx/wear/watchfacepush/WatchFacePush.kt+class:androidx.wear.watchfacepush.WatchFacePushManager) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/wear-watchfacepush#1.0.0)

*** ** * ** ***


```
interface WatchFacePushManager
```

<br />

*** ** * ** ***

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 |
|---|
| `class https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.AddWatchFaceException : https://developer.android.com/reference/java/lang/Exception.html` An exception that can be thrown by `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#addWatchFace(android.os.ParcelFileDescriptor,kotlin.String)` |
| `class https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.IsWatchFaceActiveException : https://developer.android.com/reference/java/lang/Exception.html` An exception that can be thrown by `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#isWatchFaceActive(kotlin.String)` |
| `class https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.ListWatchFacesException : https://developer.android.com/reference/java/lang/Exception.html` An exception that can be thrown by `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#listWatchFaces()` |
| `class https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.ListWatchFacesResponse` Represents the response from listing watch faces. |
| `class https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.RemoveWatchFaceException : https://developer.android.com/reference/java/lang/Exception.html` An exception that can be thrown by `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#removeWatchFace(kotlin.String)` |
| `class https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.SetWatchFaceAsActiveException : https://developer.android.com/reference/java/lang/Exception.html` An exception that can be thrown by `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#setWatchFaceAsActive(kotlin.String)` |
| `class https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.UpdateWatchFaceException : https://developer.android.com/reference/java/lang/Exception.html` An exception that can be thrown by `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#updateWatchFace(kotlin.String,android.os.ParcelFileDescriptor,kotlin.String)` |
| `class https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.WatchFaceDetails` Details about a watch face that is installed through this API. |

| ### Public functions |
|---|---|
| `suspend https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.WatchFaceDetails` | `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#addWatchFace(android.os.ParcelFileDescriptor,kotlin.String)(apkFd: https://developer.android.com/reference/android/os/ParcelFileDescriptor.html, validationToken: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Adds a new watch face. |
| `suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#isWatchFaceActive(kotlin.String)(watchfacePackageName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Checks if a watch face with the given package name is active. |
| `suspend https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.ListWatchFacesResponse` | `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#listWatchFaces()()` Lists all watch faces that were added by the app invoking this method. |
| `suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#removeWatchFace(kotlin.String)(slotId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Removes an existing watch face that was previously added by this application. |
| `suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#setWatchFaceAsActive(kotlin.String)(slotId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Sets a watch face with the given slot ID as the active watch face. |
| `suspend https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.WatchFaceDetails` | `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#updateWatchFace(kotlin.String,android.os.ParcelFileDescriptor,kotlin.String)( slotId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, apkFd: https://developer.android.com/reference/android/os/ParcelFileDescriptor.html, validationToken: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html )` Updates a watch face slot with a new watch face. |

## 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 `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#setWatchFaceAsActive(kotlin.String)`.

| Parameters |
|---|---|
| `apkFd: https://developer.android.com/reference/android/os/ParcelFileDescriptor.html` | The `https://developer.android.com/reference/android/os/ParcelFileDescriptor.html` containing the watch face APK. |
| `validationToken: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | A token proving that the watch face has gone through the required validation checks. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.WatchFaceDetails` | The `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.WatchFaceDetails` representing the added watch face in its assigned slot. |

| Throws |
|---|---|
| `https://developer.android.com/reference/kotlin/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 `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.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.**

Warning: When calling `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#updateWatchFace(kotlin.String,android.os.ParcelFileDescriptor,kotlin.String)`, don't call `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#isWatchFaceActive(kotlin.String)` immediately afterwards as this can lead to unexpected results: It can take a little time for the watch face swap to settle. Instead, first determine whether the calling app has the active watch face as shown in the previous snippet, and then call `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#updateWatchFace(kotlin.String,android.os.ParcelFileDescriptor,kotlin.String)`. If `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#updateWatchFace(kotlin.String,android.os.ParcelFileDescriptor,kotlin.String)` completes successfully, you can assume the app will still have control of the active watch face at that point.

| Parameters |
|---|---|
| `watchfacePackageName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The package name of the watch face to check. |

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `true` if the watch face is active, `false` otherwise. |

| Throws |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.IsWatchFaceActiveException` | if there is an error while checking if the watch face is active. This could happen if the provided `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#isWatchFaceActive(kotlin.String)` is invalid or if the Watch Face Push service on the watch cannot be accessed. See `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.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 |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.ListWatchFacesResponse` | A `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.ListWatchFacesResponse` containing the list of installed watch face details and the number of available slots for this application. |

| Throws |
|---|---|
| `https://developer.android.com/reference/kotlin/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 `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.ListWatchFacesException#errorCode()` for details. |

### removeWatchFace

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/wear-watchfacepush#1.0.0)

```
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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The unique identifier of the watch face to be removed. This ID corresponds to the `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.WatchFaceDetails#slotId()` of the watch face. |

| Throws |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.RemoveWatchFaceException` | if there is an error while removing the watch face. This could happen if the provided `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#removeWatchFace(kotlin.String)` is invalid or if the Watch Face Push service on the watch cannot be accessed. See `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.RemoveWatchFaceException#errorCode()` for details. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#addWatchFace(android.os.ParcelFileDescriptor,kotlin.String)` |   |

### setWatchFaceAsActive

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/wear-watchfacepush#1.0.0)

```
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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The slot ID of the watch face to set as active. |

| Throws |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.SetWatchFaceAsActiveException` | if there is an error while setting the watch face as active. This could happen if the provided `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager#setWatchFaceAsActive(kotlin.String)` 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 `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.SetWatchFaceAsActiveException#errorCode()` for details. |

### updateWatchFace

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

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 |
|---|---|
| `slotId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The slot ID to update. |
| `apkFd: https://developer.android.com/reference/android/os/ParcelFileDescriptor.html` | The `https://developer.android.com/reference/android/os/ParcelFileDescriptor.html` containing the new watch face APK. |
| `validationToken: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | A token proving that the watch face has gone through the required validation checks. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.WatchFaceDetails` | The `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.WatchFaceDetails` representing the updated watch face in the specified slot. |

| Throws |
|---|---|
| `https://developer.android.com/reference/kotlin/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 `https://developer.android.com/reference/kotlin/androidx/wear/watchfacepush/WatchFacePushManager.UpdateWatchFaceException#errorCode()` for the possible errors thrown by this method if the watch face cannot be updated. |