タイルのバージョニング

Wear OS デバイスでは、タイルは独立したバージョニングを持つ 2 つの主要コンポーネントによってレンダリングされます。アプリのタイルがすべてのデバイスで正しく機能するようにするには、この基盤となるアーキテクチャを理解することが重要です。

  • Jetpack タイル関連のライブラリ: これらのライブラリ（Wear Tiles や Wear ProtoLayout など）はアプリに埋め込まれており、デベロッパーがバージョンを管理します。アプリは、これらのライブラリを使用して、システムの onTileRequest() 呼び出しに応答して TileBuilder.Tile オブジェクト（タイルを表すデータ構造）を作成します。
  • ProtoLayout レンダラ: このシステム コンポーネントは、ディスプレイに Tile オブジェクトをレンダリングし、ユーザー操作を処理します。レンダラ バージョンはアプリ デベロッパーによって制御されず、ハードウェアが同じデバイスでも異なる場合があります。

タイルの外観や動作は、アプリの Jetpack Tiles ライブラリのバージョンと、ユーザーのデバイスの ProtoLayout レンダラ バージョンの両方によって異なる場合があります。たとえば、あるデバイスでは回転や心拍数データの表示がサポートされている一方、別のデバイスではサポートされていない場合があります。

このドキュメントでは、アプリを Tiles ライブラリと ProtoLayout レンダラがサポートするさまざまなバージョンと互換性を持たせる方法と、Jetpack ライブラリの新しいバージョンに移行する方法について説明します。

互換性を考慮する

さまざまなデバイスで正しく機能するタイルを作成するには、次の点を考慮する必要があります。

レンダラ バージョンを検出する

  • onTileRequest() メソッドに渡された DeviceParameters オブジェクトの getRendererSchemaVersion() メソッドを使用します。このメソッドは、デバイス上の ProtoLayout レンダラのメジャー バージョン番号とマイナー バージョン番号を返します。
  • 次に、onTileRequest() 実装で条件付きロジックを使用して、検出されたレンダラ バージョンに基づいてタイルのデザインや動作を適応させることができます。
    • たとえば、特定のアニメーションがサポートされていない場合は、代わりに静止画像を表示できます。

@RequiresSchemaVersion アノテーション

  • ProtoLayout メソッドの @RequiresSchemaVersion アノテーションは、そのメソッドがドキュメントに従って動作するために必要な最小レンダラ スキーマ バージョンを示します（例）。
    • デバイスで利用可能なレンダラ バージョンよりも高いバージョンを必要とするメソッドを呼び出してもアプリはクラッシュしませんが、コンテンツが表示されない、または機能が無視される可能性があります。

例

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

異なるレンダラ バージョンでテストする

さまざまなレンダラ バージョンでタイルをテストするには、さまざまなバージョンの Wear OS エミュレータにタイルをデプロイします。（実機では、ProtoLayout レンダラ アップデートは Google Play ストアまたはシステム アップデートによって配信されます。特定のレンダラ バージョンを強制的にインストールすることはできません）。

Android Studio のタイル プレビュー機能は、コードが依存する Jetpack ProtoLayout ライブラリに埋め込まれたレンダラを使用します。別の方法として、タイルをテストするときに異なる Jetpack ライブラリ バージョンに依存することもできます。

Jetpack ライブラリをアップグレードする

Jetpack Tile ライブラリを更新して、タイルをシステムとシームレスに統合するための UI の変更など、最新の機能強化を活用しましょう。

Tiles 1.2 / ProtoLayout 1.0 に移行する

バージョン 1.2 ではタイル レイアウト API のほとんどは androidx.wear.protolayout 名前空間にあります。最新の API を使用するには、コードで以下の移行手順を実行してください。

依存関係を更新する

アプリ モジュールのビルドファイルを次のように変更します。

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

名前空間を更新する

アプリの Kotlin ベースと Java ベースのコードファイルを次のように更新します。または、こちらの名前空間名変更スクリプトを実行することもできます。

  1. すべての androidx.wear.tiles.material.* インポートを androidx.wear.protolayout.material.* に置き換えます。androidx.wear.tiles.material.layouts ライブラリでもこのステップを実行します。

  2. 他の androidx.wear.tiles.* インポートのほとんどを androidx.wear.protolayout.* に置き換えます。

    androidx.wear.tiles.EventBuilders、androidx.wear.tiles.RequestBuilders、androidx.wear.tiles.TileBuilders、androidx.wear.tiles.TileService のインポートはそのままにします。

  3. TileService クラスと TileBuilder クラスの非推奨のメソッドの名前を変更します。

    1. TileBuilders: getTimeline() から getTileTimeline()、setTimeline() から setTileTimeline() に変更
    2. TileService: onResourcesRequest() から onTileResourcesRequest() に変更
    3. RequestBuilders.TileRequest: getDeviceParameters() から getDeviceConfiguration()、setDeviceParameters() から setDeviceConfiguration()、getState() から getCurrentState()、setState() から setCurrentState() に変更