Cette page a été traduite par l'API Cloud Translation.

Configurer votre application Wear OS pour le transfert de cadran
Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

La fonctionnalité Push de cadran 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.watchface:watchface-push:1.3.0-alpha07")

Ajoutez les éléments suivants à 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 = WatchFacePushManager(context)

WatchFacePushManager permet d'accéder à toutes les méthodes d'interaction avec le transfert de cadran.

Utiliser des emplacements

Les emplacements sont un concept clé lorsque vous travaillez avec le transfert de cadran. 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 permet d'identifier le cadran sur lequel effectuer l'opération.

Cadrans de liste

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 l'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

Si des emplacements sont disponibles, comme déterminé par 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.
}

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 entièrement 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.
}

Vous vous assurerez ainsi que votre cadran sera toujours disponible dans le sélecteur de cadran du système, qu'il pourra comporter votre logo de manière bien visible et même un bouton permettant de lancer votre application Marketplace sur le téléphone.

Vérifier si votre cadran est actif

Déterminer si votre place de marché a défini le cadran actif est important pour garantir une expérience fluide à l'utilisateur: si la place de marché a déjà défini le cadran actif, si l'utilisateur souhaite choisir un autre cadran, il lui suffit de remplacer le cadran actuel via l'application de la place de marché pour que cela soit pris en compte. Toutefois, si la marketplace n'a pas défini le cadran actif, l'application pour téléphone doit fournir plus d'instructions à l'utilisateur. Consultez la section sur l'application pour téléphone pour en savoir plus sur la gestion de cette expérience utilisateur.

Pour déterminer si la marketplace a défini le cadran actif:

Fournir un cadran par défaut

La fonctionnalité Push de cadran permet d'installer un cadran par défaut lorsque votre application de place de marché est installée. Cela ne définit pas automatiquement ce cadran par défaut comme actif (voir la section "Définir le cadran actif"), mais garantit que votre cadran est disponible dans l'outil de sélection du cadran du système.

Pour utiliser cette fonctionnalité :

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

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" />

Définir le cadran actif

Le transfert de cadran permet à l'application de place de marché de définir le cadran actif.

Cela signifie spécifiquement que l'application peut définir le cadran actif sur un cadran appartenant à la place de marché si le cadran actif actuel n'appartient pas à la place de marché. Notez que si la place de marché dispose déjà du cadran actif, vous pouvez le remplacer par un autre cadran en appelant updateWatchFace pour remplacer le contenu de l'emplacement du cadran par un autre cadran.

Pour définir le cadran actif, procédez comme suit:

Obtenez l'autorisation Android requise pour définir le cadran actif.
Appelez la méthode setWatchFaceAsActive.

Obtenir les autorisations nécessaires 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 demander cette autorisation à l'utilisateur lors de son exécution (utilisez la bibliothèque Accompanist pour vous aider).

Définir le cadran comme actif

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

watchFacePushManager.setWatchFaceAsActive(slotId)

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

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

Cependant, 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 de cadran.

Cette légère variation se reflète ensuite dans chacun 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()

Points à prendre en compte

Lorsque vous implémentez le transfert de cadran dans votre application, vous devez tenir compte de plusieurs éléments importants, comme la consommation d'énergie, le cache, la mise à jour des cadrans groupés 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 de place de marché:

Votre application doit s'exécuter aussi peu et aussi rarement que possible (sauf si l'utilisateur interagit directement avec elle). Par exemple :
- Réduire le réveil de l'application depuis l'application Téléphone
- Minimiser l'exécution des tâches WorkManager
Planifiez les rapports d'analyse pour le moment où la montre est en charge :
1. Si vous souhaitez générer des statistiques d'utilisation à partir de l'application Wear OS ou de toute autre métrique, utilisez WorkManager avec la contrainte requiresCharging.
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 un accès au Wi-Fi pour télécharger rapidement les APK mis à jour, puis libérez le réseau une fois terminé.
3. Ces mêmes conseils s'appliquent lorsque la place de marché propose un cadran du jour. Préchargez-le pendant que la montre se recharge.
Ne planifiez pas de tâches pour vérifier le cadran actif :
1. Vérifier régulièrement si votre place de marché dispose toujours du cadran actif et de quel cadran il s'agit a un impact sur la batterie. Évitez cette approche.
Ne pas utiliser les notifications sur la montre :
1. Si votre application utilise des notifications, concentrez-vous sur le téléphone, où l'action de l'utilisateur ouvre l'application pour poursuivre le parcours. Assurez-vous qu'ils ne sont pas mis en correspondance avec 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 de l'énergie de retransmission, envisagez d'implémenter un petit cache sur l'appareil Wear OS pour 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 presque instantanée.

De même, vous pouvez utiliser cette fonctionnalité pour pré-cacher le cadran du jour ou des schémas similaires où les cadrans sont téléchargés pendant que l'appareil Wear OS se recharge.

Mettre à jour les cadrans groupés

Votre application peut inclure un composant de cadran par défaut, comme décrit précédemment. Il est important de noter que, même si ce cadran est installé sur le système lorsque votre application de place de marché est installée, il n'est pas mis à jour si une version plus récente est associée à une mise à jour de votre application de place de marché.

Pour gérer cette situation, votre application de place de marché doit écouter l'action de diffusion MY_PACKAGE_REPLACED et vérifier si un cadran groupé doit être mis à jour à partir des composants 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 place de marché: le cadran est installé lorsque votre place de marché l'est, de sorte que les utilisateurs puissent le trouver dans la galerie de cadrans.

Voici quelques points à prendre en compte lorsque vous travaillez avec des cadrans par défaut:

N'utilisez pas removeWatchFace si l'utilisateur choisit de désinstaller un cadran de votre application de place de marché. Dans ce cas, rétablissez 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.
Faites en sorte que le cadran par défaut soit simple et immédiatement reconnaissable grâce à votre logo et à votre thématisation. Cela permet aux utilisateurs de le trouver dans la galerie de cadrans.
Ajoutez un bouton au cadran par défaut pour ouvrir l'application Téléphone. Pour ce faire, procédez 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.