# 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)

*** ** * ** ***


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

| ### Public methods |
|---|---|
| `abstract @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/watchfacepush/WatchFacePushManager.WatchFaceDetails` | `https://developer.android.com/reference/androidx/wear/watchfacepush/WatchFacePushManager#addWatchFace(android.os.ParcelFileDescriptor,kotlin.String)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/os/ParcelFileDescriptor.html apkFd, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html validationToken )` Adds a new watch face. |
| `abstract boolean` | `https://developer.android.com/reference/androidx/wear/watchfacepush/WatchFacePushManager#isWatchFaceActive(kotlin.String)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html watchfacePackageName)` Checks if a watch face with the given package name is active. |
| `abstract @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/watchfacepush/WatchFacePushManager.ListWatchFacesResponse` | `https://developer.android.com/reference/androidx/wear/watchfacepush/WatchFacePushManager#listWatchFaces()()` Lists all watch faces that were added by the app invoking this method. |
| `abstract void` | `https://developer.android.com/reference/androidx/wear/watchfacepush/WatchFacePushManager#removeWatchFace(kotlin.String)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html slotId)` Removes an existing watch face that was previously added by this application. |
| `abstract void` | `https://developer.android.com/reference/androidx/wear/watchfacepush/WatchFacePushManager#setWatchFaceAsActive(kotlin.String)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html slotId)` Sets a watch face with the given slot ID as the active watch face. |
| `abstract @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/watchfacepush/WatchFacePushManager.WatchFaceDetails` | `https://developer.android.com/reference/androidx/wear/watchfacepush/WatchFacePushManager#updateWatchFace(kotlin.String,android.os.ParcelFileDescriptor,kotlin.String)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html slotId, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/os/ParcelFileDescriptor.html apkFd, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html 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 `https://developer.android.com/reference/androidx/wear/watchfacepush/WatchFacePushManager#setWatchFaceAsActive(kotlin.String)`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/os/ParcelFileDescriptor.html apkFd` | The `https://developer.android.com/reference/android/os/ParcelFileDescriptor.html` containing the watch face APK. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html validationToken` | A token proving that the watch face has gone through the required validation checks. |

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

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

Warning: When calling `https://developer.android.com/reference/androidx/wear/watchfacepush/WatchFacePushManager#updateWatchFace(kotlin.String,android.os.ParcelFileDescriptor,kotlin.String)`, don't call `https://developer.android.com/reference/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/androidx/wear/watchfacepush/WatchFacePushManager#updateWatchFace(kotlin.String,android.os.ParcelFileDescriptor,kotlin.String)`. If `https://developer.android.com/reference/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html watchfacePackageName` | The package name of the watch face to check. |

| Returns |
|---|---|
| `boolean` | `true` if the watch face is active, `false` otherwise. |

| Throws |
|---|---|
| `https://developer.android.com/reference/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/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/androidx/wear/watchfacepush/WatchFacePushManager.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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/watchfacepush/WatchFacePushManager.ListWatchFacesResponse` | A `https://developer.android.com/reference/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/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/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)

```
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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html slotId` | The unique identifier of the watch face to be removed. This ID corresponds to the `https://developer.android.com/reference/androidx/wear/watchfacepush/WatchFacePushManager.WatchFaceDetails#slotId()` of the watch face. |

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

| See also |
|---|---|
| `https://developer.android.com/reference/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)

```
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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html slotId` | The slot ID of the watch face to set as active. |

| Throws |
|---|---|
| `https://developer.android.com/reference/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/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/androidx/wear/watchfacepush/WatchFacePushManager.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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html slotId` | The slot ID to update. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/os/ParcelFileDescriptor.html apkFd` | The `https://developer.android.com/reference/android/os/ParcelFileDescriptor.html` containing the new watch face APK. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html validationToken` | A token proving that the watch face has gone through the required validation checks. |

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

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