Controllo delle versioni delle schede

Sui dispositivi Wear OS, i riquadri vengono visualizzati da due componenti chiave con versionamento indipendente. Per assicurarti che i riquadri delle app funzionino correttamente su tutti i dispositivi, è importante comprendere questa architettura di base.

  • Librerie relative ai riquadri di Jetpack: queste librerie (inclusi Wear Tiles e Wear ProtoLayout) sono incorporate nella tua app e tu, in qualità di sviluppatore, controlli le relative versioni. L'app utilizza queste librerie per creare un oggetto TileBuilder.Tile (la struttura di dati che rappresenta il riquadro) in risposta alla chiamata onTileRequest() del sistema.
  • ProtoLayout Renderer:questo componente di sistema è responsabile del rendering dell'oggetto Tile sul display e della gestione delle interazioni utente. La versione del visualizzatore non è controllata dallo sviluppatore dell'app e può variare da un dispositivo all'altro, anche se hanno hardware identico.

L'aspetto o il comportamento di una scheda può variare in base alle versioni della libreria Jetpack Tiles della tua app e alla versione del Renderer ProtoLayout sul dispositivo dell'utente. Ad esempio, un dispositivo potrebbe supportare la rotazione o la visualizzazione dei dati sulla frequenza cardiaca, mentre un altro potrebbe non farlo.

Questo documento spiega come assicurarti che la tua app sia compatibile con le diverse versioni della libreria Tiles e del Renderer ProtoLayout e come eseguire la migrazione a versioni più recenti della libreria Jetpack.

Prendi in considerazione la compatibilità

Per creare un riquadro che funzioni correttamente su una serie di dispositivi, devi tenere conto di quanto segue.

Rileva la versione del renderer

  • Utilizza il metodo getRendererSchemaVersion() dell'oggetto DeviceParameters passato al metodo onTileRequest(). Questo metodo restituisce i numeri di versione maggiore e minore di ProtoLayout Renderer sul dispositivo.
  • Puoi quindi utilizzare la logica condizionale nell'implementazione di onTileRequest() per adattare il design o il comportamento del riquadro in base alla versione del visualizzatore rilevata.
    • Ad esempio, se un'animazione specifica non è supportata, puoi visualizzare un'immagine statica.

L'annotazione @RequiresSchemaVersion

  • L'annotazione @RequiresSchemaVersion sui metodi ProtoLayout indica la versione minima dello schema del renderer richiesta per il comportamento del metodo come documentato (esempio).
    • L'uso di un metodo che richiede una versione del renderer superiore a quella disponibile sul dispositivo non causerà l'arresto anomalo dell'app, ma potrebbe comportare la mancata visualizzazione dei contenuti o l'ignoranza della funzionalità.

Esempio

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

Esegui test con versioni diverse del renderer

Per testare i riquadri con versioni diverse del renderer, esegui il deployment in versioni diverse dell'emulatore Wear OS. Sui dispositivi fisici, gli aggiornamenti di ProtoLayout Renderer vengono distribuiti tramite il Play Store o gli aggiornamenti di sistema. Non è possibile forzare l'installazione di una versione specifica del renderer.

La funzionalità Anteprima riquadri di Android Studio utilizza un visualizzatore incorporato nella libreria Jetpack ProtoLayout da cui dipende il codice, quindi un altro approccio è fare affidamento su versioni diverse della libreria Jetpack durante il test dei riquadri.

Eseguire l'upgrade delle librerie Jetpack

Aggiorna le librerie Jetpack Tile per usufruire dei più recenti miglioramenti, tra cui le modifiche all'interfaccia utente per integrare perfettamente i riquadri con il sistema.

Eseguire la migrazione a Tiles 1.2 / ProtoLayout 1.0

A partire dalla versione 1.2, la maggior parte delle API di layout delle riquadri si trova nello spazio dei nomi androidx.wear.protolayout. Per utilizzare le API più recenti, completa i seguenti passaggi di migrazione nel tuo codice.

Aggiorna le dipendenze

Nel file di build del modulo dell'app, apporta le seguenti modifiche:

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

Aggiorna gli spazi dei nomi

Apporta i seguenti aggiornamenti ai file di codice basati su Kotlin e Java della tua app. In alternativa, puoi eseguire questo script di rinominazione dello spazio dei nomi.

  1. Sostituisci tutte le importazioni di androidx.wear.tiles.material.* con androidx.wear.protolayout.material.*. Completa questo passaggio anche per la biblioteca androidx.wear.tiles.material.layouts.

  2. Sostituisci la maggior parte delle altre importazioni di androidx.wear.tiles.* con androidx.wear.protolayout.*.

    Le importazioni per androidx.wear.tiles.EventBuilders, androidx.wear.tiles.RequestBuilders, androidx.wear.tiles.TileBuilders e androidx.wear.tiles.TileService dovrebbero rimanere invariate.

  3. Rinomina alcuni metodi deprecati delle classi TileService e TileBuilder:

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