Gestion des versions des cartes

Sur les appareils Wear OS, les cartes sont affichées par deux composants clés avec une gestion des versions indépendante. Pour vous assurer que les cartes de vos applications fonctionnent correctement sur tous les appareils, il est important de comprendre cette architecture sous-jacente.

  • Bibliothèques liées aux cartes Jetpack: ces bibliothèques (y compris Wear Tiles et Wear ProtoLayout) sont intégrées à votre application, et vous, en tant que développeur, contrôlez leurs versions. Votre application utilise ces bibliothèques pour créer un objet TileBuilder.Tile (la structure de données représentant votre carte) en réponse à l'appel onTileRequest() du système.
  • ProtoLayout Renderer:ce composant système est responsable de l'affichage de l'objet Tile à l'écran et de la gestion des interactions utilisateur. La version du moteur de rendu n'est pas contrôlée par le développeur de l'application et peut varier d'un appareil à l'autre, même ceux dont le matériel est identique.

L'apparence ou le comportement d'une carte peut varier en fonction des versions de la bibliothèque Jetpack Tiles de votre application et de la version du moteur de rendu ProtoLayout sur l'appareil de l'utilisateur. Par exemple, un appareil peut prendre en charge la rotation ou l'affichage des données de fréquence cardiaque, et un autre non.

Ce document explique comment vous assurer que votre application est compatible avec différentes versions de la bibliothèque Tiles et du moteur de rendu ProtoLayout, et comment migrer vers des versions supérieures de la bibliothèque Jetpack.

Tenir compte de la compatibilité

Pour créer une carte qui fonctionne correctement sur une gamme d'appareils, vous devez tenir compte des points suivants.

Détecter la version du moteur de rendu

  • Utilisez la méthode getRendererSchemaVersion() de l'objet DeviceParameters transmis à votre méthode onTileRequest(). Cette méthode renvoie les numéros de version majeure et mineure du moteur de rendu ProtoLayout sur l'appareil.
  • Vous pouvez ensuite utiliser une logique conditionnelle dans votre implémentation onTileRequest() pour adapter la conception ou le comportement de votre carte en fonction de la version du moteur de rendu détectée.
    • Par exemple, si une animation spécifique n'est pas prise en charge, vous pouvez afficher une image statique à la place.

@RequiresSchemaVersion annotation

  • L'annotation @RequiresSchemaVersion sur les méthodes ProtoLayout indique la version minimale du schéma du moteur de rendu requise pour que cette méthode se comporte comme indiqué dans la documentation (exemple).
    • Bien que l'appel d'une méthode nécessitant une version de rendu supérieure à celle disponible sur l'appareil ne provoque pas le plantage de votre application, il peut entraîner l'absence d'affichage du contenu ou l'ignorer.

Exemple

override fun onTileRequest(
    requestParams: TileService.TileRequest
): ListenableFuture<Tile> {
    val rendererVersion =
        requestParams.deviceConfiguration.rendererSchemaVersion
    val tile = Tile.Builder()

    if (
        rendererVersion.major > 1 ||
            (rendererVersion.major == 1 && rendererVersion.minor >= 300)
    ) {
        // Use a feature supported in renderer version 1.300 or later
        tile.setTileTimeline(/* ... */ )
    } else {
        // Provide fallback content for older renderers
        tile.setTileTimeline(/* ... */ )
    }

    return Futures.immediateFuture(tile.build())
}

Tester avec différentes versions du moteur de rendu

Pour tester vos cartes sur différentes versions de moteur de rendu, déployez-les sur différentes versions de l'émulateur Wear OS. (Sur les appareils physiques, les mises à jour du moteur de rendu ProtoLayout sont fournies par le Play Store ou les mises à jour du système. Il n'est pas possible de forcer l'installation d'une version de rendu spécifique.)

La fonctionnalité d'aperçu des cartes d'Android Studio utilise un moteur de rendu intégré à la bibliothèque Jetpack ProtoLayout sur laquelle votre code dépend. Une autre approche consiste donc à dépendre de différentes versions de la bibliothèque Jetpack lors des tests des cartes.

Mettre à niveau les bibliothèques Jetpack

Mettez à jour vos bibliothèques de cartes Jetpack pour profiter des dernières améliorations, y compris des modifications de l'interface utilisateur pour intégrer vos cartes de manière transparente au système.

Migrer vers Tiles 1.2 / ProtoLayout 1.0

Depuis la version 1.2, la plupart des API de mise en page de cartes se trouvent dans l'espace de noms androidx.wear.protolayout. Pour utiliser les dernières API, suivez la procédure de migration suivante dans votre code.

Mettre à jour les dépendances

Dans le fichier de compilation de votre module d'application, apportez les modifications suivantes :

Groovy

  // Remove
  implementation 'androidx.wear.tiles:tiles-material:version'

  // Include additional dependencies
  implementation "androidx.wear.protolayout:protolayout:1.2.1"
  implementation "androidx.wear.protolayout:protolayout-material:1.2.1"
  implementation "androidx.wear.protolayout:protolayout-expression:1.2.1"

  // Update
  implementation "androidx.wear.tiles:tiles:1.4.1"

Kotlin

  // Remove
  implementation("androidx.wear.tiles:tiles-material:version")

  // Include additional dependencies
  implementation("androidx.wear.protolayout:protolayout:1.2.1")
  implementation("androidx.wear.protolayout:protolayout-material:1.2.1")
  implementation("androidx.wear.protolayout:protolayout-expression:1.2.1")

  // Update
  implementation("androidx.wear.tiles:tiles:1.4.1")

Mettre à jour les espaces de noms

Dans les fichiers de code basés sur Kotlin et Java de votre application, effectuez les mises à jour suivantes. Vous pouvez également exécuter ce script de modification du nom d'un espace de noms.

  1. Remplacez toutes les importations androidx.wear.tiles.material.* par androidx.wear.protolayout.material.*. Effectuez également cette étape pour la bibliothèque androidx.wear.tiles.material.layouts.

  2. Remplacez la plupart des autres importations androidx.wear.tiles.* par androidx.wear.protolayout.*.

    Les importations pour androidx.wear.tiles.EventBuilders, androidx.wear.tiles.RequestBuilders, androidx.wear.tiles.TileBuilders et androidx.wear.tiles.TileService ne doivent pas changer.

  3. Renommez quelques méthodes obsolètes des classes TileService et TileBuilder :

    1. TileBuilders : getTimeline() en getTileTimeline(), et setTimeline() en setTileTimeline()
    2. TileService : onResourcesRequest() en onTileResourcesRequest()
    3. RequestBuilders.TileRequest : getDeviceParameters() en getDeviceConfiguration(), setDeviceParameters() en setDeviceConfiguration(), getState() en getCurrentState(), et setState() en setCurrentState()