Configurer votre application Wear OS pour le transfert de cadran

Watch Face Push permet à votre application de gérer les cadrans sur un appareil Wear OS. Cela inclut l'ajout, la mise à jour et la suppression de cadrans, ainsi que la définition du cadran actif. Configurez votre application Wear OS pour qu'elle utilise l'API Watch Face Push.

Configuration

Incluez la dépendance androidx.wear.watchfacepush:watchfacepush dans votre fichier build.gradle.kts.

Ajoutez le code suivant à votre AndroidManifest.xml :

<!-- Required to use the Watch Face Push API.  -->
<uses-permission android:name="com.google.wear.permission.PUSH_WATCH_FACES" />

Obtenir une référence à l'instance du gestionnaire

Obtenez une instance de WatchFacePushManager :

val watchFacePushManager = WatchFacePushManagerFactory.createWatchFacePushManager(context)

WatchFacePushManager fournit un accès à toutes les méthodes d'interaction avec Watch Face Push.

Utiliser les emplacements

Lorsque vous travaillez avec Watch Face Push, un concept clé est celui des emplacements. Les emplacements permettent d'adresser les cadrans installés qui appartiennent à votre application. Le système définit un nombre maximal d'emplacements qu'une place de marché peut avoir. Avec Wear OS 6, la limite est de 1.

Lors de la mise à jour ou de la suppression d'un cadran, slotId est utilisé pour identifier le cadran sur lequel effectuer l'opération.

Lister les cadrans

Pour lister l'ensemble des cadrans installés, utilisez listWatchFaces() :

val response = watchFacePushManager.listWatchFaces()
val installedList = response.installedWatchFaceDetails
installedList.forEach {
    Log.i(TAG, "Installed watchface: ${it.packageName}")
}

val remainingSlots = response.remainingSlotCount
Log.i(TAG, "Remaining slots: $remainingSlots")

Cela vous permet de déterminer si l'emplacement est disponible ou si l'ajout d'un autre cadran nécessite de remplacer celui existant. La liste fournit également des informations sur le cadran installé. Par exemple, pour vérifier si un package de cadran donné est installé :

suspend fun isInstalled(packageName: String) = watchFacePushManager.listWatchFaces()
    .installedWatchFaceDetails.any { it.packageName == packageName }

Ajouter un cadran

S'il y a des créneaux disponibles, comme indiqué dans la réponse listWatchFaces, la méthode addWatchFace() doit être utilisée :

try {
    // Supply the validation token along with the watch face package data itself.
    val slot = watchFacePushManager.addWatchFace(parcelFileDescriptor, token)
    Log.i(TAG, "${slot.packageName} (${slot.versionCode}) added in slot ${slot.slotId}")
} catch (e: WatchFacePushManager.AddWatchFaceException) {
    Log.e(TAG, "Something went wrong installing the watch face", e)
}

Mettre à jour un cadran

La mise à jour d'un cadran vous permet de remplacer le contenu d'un emplacement donné par un nouveau package. Il peut s'agir de mettre à niveau le même cadran vers une version plus récente ou de le remplacer complètement par un autre.

// Replacing the com.example.watchfacepush.green watch face with
// com.example.watchfacepush.red
val slotId =
    watchFacePushManager.listWatchFaces().installedWatchFaceDetails
        .firstOrNull { it.packageName == "com.example.watchfacepush.green" }?.slotId
        ?: throw IllegalArgumentException("No green watch face found")
try {
    watchFacePushManager.updateWatchFace(slotId, redParcelFileDesc, redValidationToken)
} catch (e: WatchFacePushManager.UpdateWatchFaceException) {
    Log.e(TAG, "Something went wrong updating the watch face", e)
}

Supprimer un cadran

Pour supprimer un cadran :

// Remove the com.example.watchfacepush.green watch face.
val slotId =
    watchFacePushManager.listWatchFaces().installedWatchFaceDetails
        .firstOrNull { it.packageName == "com.example.watchfacepush.green" }?.slotId
        ?: throw IllegalArgumentException("No green watch face found")

try {
    watchFacePushManager.removeWatchFace(slotId)
} catch (e: WatchFacePushManager.RemoveWatchFaceException) {
    Log.e(TAG, "Something went wrong removing the watch face", e)
}

Cette approche signifie que votre cadran est toujours disponible dans le sélecteur de cadran système. Vous pouvez mettre en avant votre logo et même ajouter un bouton pour lancer votre application Marketplace sur le téléphone.

Vérifier si votre cadran est actif

Il est important de déterminer si votre plate-forme a défini le cadran actif pour offrir une expérience fluide à l'utilisateur. Si la plate-forme a déjà défini le cadran actif, l'utilisateur n'a qu'à remplacer le cadran actuel par celui de son choix dans l'application de la plate-forme pour que le changement prenne effet. Toutefois, si le marché ne dispose pas du cadran actif défini, l'application pour téléphone doit fournir plus d'informations à l'utilisateur. Pour en savoir plus sur la gestion de cette expérience utilisateur, consultez la section sur l'application mobile.

Pour déterminer si le cadran actif est défini sur la plate-forme, utilisez la logique suivante :

suspend fun hasActiveWatchFace() = watchFacePushManager.listWatchFaces()
    .installedWatchFaceDetails
    .any {
        watchFacePushManager.isWatchFaceActive(it.packageName)
    }

Fournir un cadran par défaut

La fonctionnalité Watch Face Push permet d'installer un cadran par défaut lorsque votre application Marketplace est installée. Cela ne définit pas, en soi, ce cadran par défaut comme actif (voir la définition du cadran actif), mais rend votre cadran disponible dans le sélecteur de cadran système.

Pour utiliser cette fonctionnalité :

  1. Dans la compilation de votre application Wear OS, incluez le cadran par défaut dans le chemin d'accès : assets/default_watchface.apk

  2. Ajoutez l'entrée suivante à votre AndroidManifest.xml

    <meta-data
    android:name="com.google.android.wearable.marketplace.DEFAULT_WATCHFACE_VALIDATION_TOKEN"
    android:value="@string/default_wf_token" />

Définir le cadran actif

Le Watch Face Push permet à l'application Marketplace de définir le cadran actif.

Cela signifie plus précisément que l'application peut définir le cadran actif sur un cadran appartenant au marché si le cadran actif actuel n'appartient pas au marché. Notez que si la place de marché possède déjà le cadran actif, le changement de cadran s'effectue en appelant updateWatchFace pour remplacer le contenu de l'emplacement du cadran par un autre cadran.

Pour définir le cadran actif, vous devez suivre deux étapes :

  1. Acquérir l'autorisation Android requise pour définir le cadran actif.
  2. Appelez la méthode setWatchFaceAsActive.

Acquérir les autorisations pour définir le cadran actif

L'autorisation requise est SET_PUSHED_WATCH_FACE_AS_ACTIVE, qui doit être ajoutée à votre fichier manifeste :

<!-- Required to be able to call the setWatchFaceAsActive() method. -->
<uses-permission android:name="com.google.wear.permission.SET_PUSHED_WATCH_FACE_AS_ACTIVE" />

Comme il s'agit d'une autorisation d'exécution, votre application doit la demander à l'utilisateur lorsqu'elle s'exécute (pensez à la bibliothèque Accompanist pour vous aider).

Définir le cadran comme actif

Une fois l'autorisation accordée, appelez setWatchFaceAsActive sur l'ID d'emplacement du cadran qui doit être actif.

Une fois cette méthode utilisée, votre application téléphonique devrait plutôt vous indiquer comment définir manuellement le cadran actif.

Lire des métadonnées supplémentaires à partir de l'APK de votre cadran

L'objet WatchFaceSlot permet également d'obtenir des informations supplémentaires que vous pouvez déclarer sur votre cadran.

Cela peut être particulièrement utile dans les cas où vous avez des variantes mineures du même cadran. Par exemple, vous pouvez définir un cadran comme suit :

  • Package name (nom du package) : com.myapp.watchfacepush.mywatchface
  • Version du package : 1.0.0

Toutefois, ce cadran peut se présenter sous la forme de quatre APK différents, qui sont presque identiques, mais avec des couleurs par défaut différentes : rouge, jaune, vert et bleu, définies dans un ColorConfiguration dans le fichier XML du format WFF (Watch Face Format).

Cette légère variation est ensuite reflétée dans chacune des quatre APK :

<!-- For watch face com.myapp.watchfacepush.mywatchface -->
<property
    android:name="default_color"
    android:value="red" />

L'utilisation d'une propriété personnalisée permet à votre application de déterminer laquelle de ces variantes est installée :

val color = watchFaceDetails
    .getMetaData("com.myapp.watchfacepush.mywatchface.default_color")
    .invoke()
Log.i(TAG, "Default color: $color")

Points à prendre en compte

Lorsque vous implémentez Watch Face Push dans votre application, vous devez tenir compte de plusieurs éléments importants, comme la consommation d'énergie, la mise en cache, la mise à jour des cadrans fournis et la fourniture d'un cadran par défaut représentatif.

Puissance

La consommation d'énergie est un élément clé à prendre en compte pour toute application exécutée sur Wear OS. Pour le composant Wear OS de votre application Marketplace :

  1. Votre application doit s'exécuter le moins souvent et le moins longtemps possible (sauf si l'utilisateur interagit directement avec elle). Par exemple :
    • Minimiser le réveil de l'application depuis l'application Téléphone
    • Minimiser l'exécution des jobs WorkManager
  2. Planifiez les rapports d'analyse pour qu'ils soient générés lorsque la montre est en charge.
    1. Si vous souhaitez signaler des statistiques d'utilisation de l'application Wear OS ou d'autres métriques, utilisez WorkManager avec la contrainte requiresCharging.
  3. Planifier les mises à jour lorsque la montre est en charge et utilise le Wi-Fi :
    1. Vous pouvez vérifier les versions des cadrans installés et les mettre à jour automatiquement. Encore une fois, utilisez la contrainte requiresCharging et le type de réseau UNMETERED pour requiresNetworkType.
    2. Lorsqu'il est en charge, l'appareil a probablement accès au Wi-Fi. Demandez le Wi-Fi pour télécharger rapidement les APK mis à jour, puis libérez le réseau une fois l'opération terminée.
    3. Les mêmes consignes s'appliquent lorsque la place de marché propose un cadran du jour. Téléchargez-le à l'avance pendant que la montre est en charge.
  4. Ne planifiez pas de jobs pour vérifier le cadran actif :
    1. Vérifier régulièrement si votre marketplace propose toujours le cadran actif et quel est ce cadran consomme de la batterie. Évitez cette approche.
  5. Ne pas utiliser les notifications sur la montre :
    1. Si votre application utilise des notifications, concentrez-les sur le téléphone, où l'action de l'utilisateur ouvre l'application du téléphone pour poursuivre le parcours. Configurez les notifications pour qu'elles ne soient pas transférées vers l'application Wear OS à l'aide de setLocalOnly.

Mise en cache

Dans l'exemple de place de marché canonique, les cadrans sont transférés du téléphone vers la montre. Cette connexion est généralement une connexion Bluetooth, qui peut être assez lente.

Pour offrir une meilleure expérience utilisateur et économiser la puissance de retransmission, envisagez d'implémenter un petit cache sur l'appareil Wear OS afin de stocker quelques APK.

Si l'utilisateur essaie un autre cadran, mais décide ensuite de revenir à celui qu'il avait choisi précédemment, cette action est alors presque instantanée.

De même, cela peut être utilisé pour la mise en cache préalable du cadran du jour ou de schémas similaires où les cadrans sont téléchargés lorsque l'appareil Wear OS est en charge.

Mettre à jour les cadrans fournis

Votre application peut inclure un élément de cadran par défaut, comme décrit précédemment. Il est important de noter que, bien que cette clock face soit installée sur le système lorsque votre application Marketplace est installée, elle n'est pas mise à jour si une version plus récente est incluse dans une mise à jour de votre application Marketplace.

Pour gérer cette situation, votre application Marketplace doit écouter l'action de diffusion MY_PACKAGE_REPLACED et vérifier si une mise à jour est nécessaire pour les cadrans de montre groupés à partir des éléments du package.

Cadran par défaut représentatif

Un cadran par défaut est un excellent moyen d'aider vos utilisateurs à découvrir et à utiliser votre plate-forme : le cadran est installé en même temps que votre plate-forme, ce qui permet aux utilisateurs de le trouver dans la galerie de cadrans.

Voici quelques éléments à prendre en compte lorsque vous utilisez des cadrans par défaut :

  • N'utilisez pas removeWatchFace si l'utilisateur choisit de désinstaller un cadran depuis votre application Marketplace. Dans ce cas, revenez plutôt au cadran par défaut à l'aide de updateWatchFace. Cela permet aux utilisateurs de trouver votre cadran et de le définir à partir de la galerie.
  • Rendez le cadran par défaut simple et immédiatement reconnaissable grâce à votre logo et votre thème. Cela aide les utilisateurs à le trouver dans la galerie de cadrans.

  • Ajoutez un bouton à la clock face par défaut pour ouvrir l'application Téléphone. Pour ce faire, vous pouvez procéder en deux étapes :

    1. Ajoutez un élément Launch au cadran pour lancer un intent à l'aide de l'application Wear OS, par exemple :

      <Launch target="com.myapp/com.myapp.LaunchOnPhoneActivity" />

    2. Dans LaunchOnPhoneActivity, lancez l'application Téléphone à l'aide de RemoteActivityHelper.