Control de versiones de tarjetas

En los dispositivos Wear OS, dos componentes clave renderizan tarjetas con control de versiones independiente. Para garantizar que las tarjetas de tus apps funcionen correctamente en todos los dispositivos, es importante comprender esta arquitectura subyacente.

  • Bibliotecas relacionadas con tarjetas de Jetpack: Estas bibliotecas (incluidas las tarjetas de Wear y Wear ProtoLayout) están incorporadas en tu app y, como desarrollador, controlas sus versiones. Tu app usa estas bibliotecas para crear un objeto TileBuilder.Tile (la estructura de datos que representa tu tarjeta) en respuesta a la llamada onTileRequest() del sistema.
  • Renderizador de ProtoLayout: Este componente del sistema es responsable de renderizar el objeto Tile en la pantalla y controlar las interacciones del usuario. El desarrollador de la app no controla la versión del renderizador y puede variar entre los dispositivos, incluso aquellos con hardware idéntico.

La apariencia o el comportamiento de una tarjeta pueden variar según las versiones de la biblioteca de tarjetas de Jetpack de tu app y la versión del renderizador de ProtoLayout en el dispositivo del usuario. Por ejemplo, un dispositivo puede admitir la rotación o la visualización de datos de frecuencia cardíaca, y otro no.

En este documento, se explica cómo garantizar que tu app sea compatible con diferentes versiones de la biblioteca de tarjetas y el renderizador de ProtoLayout, y cómo migrar a versiones posteriores de la biblioteca de Jetpack.

Ten en cuenta la compatibilidad

Para crear una tarjeta que funcione correctamente en una variedad de dispositivos, debes tener en cuenta lo siguiente.

Cómo detectar la versión del renderizador

  • Usa el método getRendererSchemaVersion() del objeto DeviceParameters que se pasa a tu método onTileRequest(). Este método muestra los números de versión principal y secundaria del renderizador de ProtoLayout en el dispositivo.
  • Luego, puedes usar la lógica condicional en tu implementación de onTileRequest() para adaptar el diseño o el comportamiento de tu tarjeta según la versión del renderizador detectada.
    • Por ejemplo, si no se admite una animación específica, puedes mostrar una imagen estática.

La anotación @RequiresSchemaVersion

  • La anotación @RequiresSchemaVersion en los métodos de ProtoLayout indica la versión mínima del esquema del renderizador necesaria para que ese método se comporte como se documenta (ejemplo).
    • Si bien llamar a un método que requiera una versión de renderizador superior a la que está disponible en el dispositivo no hará que tu app falle, podría provocar que no se muestre el contenido o que se ignore la función.

Ejemplo

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())
}

Prueba con diferentes versiones del renderizador

Para probar tus tarjetas con diferentes versiones del renderizador, impleméntalas en diferentes versiones del emulador de Wear OS. (En dispositivos físicos, Play Store o las actualizaciones del sistema entregan las actualizaciones del renderizador de ProtoLayout). No es posible forzar la instalación de una versión específica del renderizador).

La función Tile Preview de Android Studio usa un renderizador incorporado en la biblioteca de ProtoLayout de Jetpack de la que depende tu código, por lo que otro enfoque es depender de diferentes versiones de la biblioteca de Jetpack cuando se prueban tarjetas.

Actualiza las bibliotecas de Jetpack

Actualiza tus bibliotecas de tarjetas de Jetpack para aprovechar las mejoras más recientes, incluidos los cambios en la IU para que tus tarjetas se integren sin problemas con el sistema.

Cómo migrar a Tiles 1.2 o ProtoLayout 1.0

A partir de la versión 1.2, la mayoría de las APIs de diseño de tarjetas está en el espacio de nombres androidx.wear.protolayout. Para usar las APIs más recientes, completa los siguientes pasos de migración en tu código.

Actualiza las dependencias

En el archivo de compilación del módulo de tu app, realiza los siguientes cambios:

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

Actualiza los espacios de nombres

En los archivos de código basados en Kotlin y Java de tu app, realiza las siguientes actualizaciones. También puedes ejecutar esta secuencia de comandos de cambio de nombres de los espacios de nombres.

  1. Reemplaza todas las importaciones de androidx.wear.tiles.material.* por androidx.wear.protolayout.material.*. Realiza también este paso para la biblioteca androidx.wear.tiles.material.layouts.

  2. Reemplaza la mayoría de las demás importaciones de androidx.wear.tiles.* por androidx.wear.protolayout.*.

    Las importaciones de androidx.wear.tiles.EventBuilders, androidx.wear.tiles.RequestBuilders, androidx.wear.tiles.TileBuilders y androidx.wear.tiles.TileService deben permanecer iguales.

  3. Cambia el nombre de algunos métodos obsoletos de las clases TileService y TileBuilder:

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