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 les dépendances nécessaires :

implementation("androidx.wear.watchfacepush:watchfacepush:1.0.0-alpha01")

Ajoutez le code suivant à votre AndroidManifest.xml :

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

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

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

</manifest>

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

Obtenez une instance de WatchFacePushManager :

val manager = WatchFacePushManagerFactory.createWatchFacePushManager(context)

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

Utiliser des 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
val remainingSlots = response.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) = watchFacePush.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: AddWatchFaceException) {
    // Something went wrong adding the watch face.
}

Remarque : Ne stockez pas les valeurs slotId et ne les traitez pas comme des valeurs persistantes. L'état peut changer en dehors de votre application. Par exemple, un utilisateur peut désinstaller votre cadran via l'UI système. Obtenez toujours l'état actuel immédiatement avant toute opération basée sur des emplacements.

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

try {
    watchFacePushManager.updateWatchFace(slotId, redParcelFileDesc, redValidationToken)
} catch (e: UpdateWatchFaceException) {
    // Something went wrong updating the watch face.
}

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

try {
    watchFacePushManager.removeWatchFace(slotId)
} catch (e: RemoveWatchFaceException) {
    // Something went wrong removing the watch face.
}

Remarque : Déterminez si votre application doit appeler removeWatchFace. Au lieu de cela, lorsque l'utilisateur appuie sur une option pour désinstaller un cadran via votre application Marketplace, vous pouvez le remplacer par un cadran par défaut.

Cela permettra de s'assurer que votre cadran est toujours disponible dans le sélecteur de cadrans système, qu'il peut afficher votre logo de manière visible et qu'il peut même comporter un bouton permettant de 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 garantir 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 la place de marché n'a pas défini le cadran actif, 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 pour téléphone.

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

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

Avertissement : Lorsque vous appelez updateWatchFace(), n'appelez pas isWatchFaceActive() immédiatement après, car cela peut entraîner des résultats inattendus. Le changement de cadran peut prendre un certain temps.

Déterminez d'abord si l'application appelante possède une référence au cadran actif, comme indiqué dans l'extrait précédent, puis appelez updateWatchFace(). Si updateWatchFace() se termine correctement, vous pouvez supposer que votre application contrôle toujours le cadran actif.

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 "Définir le cadran actif"), mais garantit que votre cadran est 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 :

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

Remarque : Un schéma de compilation typique inclut la compilation de votre default_watchface.apk dans le cadre de la compilation globale de votre application en tant qu'étape de pré-compilation. Vous pouvez l'utiliser pour renseigner la valeur du fichier manifeste du jeton de validation en demandant au processus de compilation du cadran de montre par défaut de générer un fichier XML de ressources Android supplémentaire et d'inclure ce chemin d'accès aux ressources en tant que chemin d'accès aux ressources supplémentaire dans votre application principale. Cette approche est plus simple que d'essayer de manipuler le fichier manifeste lui-même pendant le processus de compilation.

Définir le cadran actif

Le Watch Face Push permet à l'application de la place de marché 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.

Obtenir 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 :

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    ...
    <uses-permission android:name="com.google.wear.permission.SET_PUSHED_WATCH_FACE_AS_ACTIVE" />
</manifest>

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

Remarque : Cette autorisation ne peut être refusée qu'une seule fois. Si l'utilisateur refuse la demande, elle ne peut plus être effectuée. Dans ce cas, l'application doit rediriger l'utilisateur vers les paramètres afin qu'il puisse ajuster manuellement l'autorisation.

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 :

watchFacePushManager.setWatchFaceAsActive(slotId)

Remarque : Vous ne pouvez définir le cadran actif de cette manière qu'une seule fois. Si l'utilisateur passe à un cadran d'un autre développeur, l'appel de cette API pour redéfinir le cadran actif sur le vôtre génère une exception.

Une fois cette méthode utilisée, votre application pour téléphone 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 :

watchFaceDetails
    .getMetaDataValues("com.myapp.watchfacepush.mywatchface.default_color")
    .invoke()

Remarque : Dans l'exemple précédent, l'espace de noms devait être indiqué pour la propriété, car none a été déclaré sur la propriété. Si la propriété inclut un point (.), cela n'est pas nécessaire. Une propriété nommée abc.def peut donc être récupérée à l'aide de getMetaDataValues("abc.def").

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 pour qu'elles s'effectuent lorsque la montre est en charge et connectée au Wi-Fi :
   1. Vous pouvez vérifier les versions des cadrans installés et les mettre à jour automatiquement. Là encore, utilisez la contrainte requiresCharging et le type de réseau UNMETERED pour requiresNetworkType.
   2. Lorsque l'appareil est en charge, il est probable qu'il ait 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 conseils 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 épuise 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. Assurez-vous que ces éléments ne sont pas transférés vers l'application de la montre à 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 le préchargement 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 clock face groupée doit être mise à jour à partir des assets 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, restaurez le 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.
• Créez un 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.