카드 버전 관리

Wear OS 기기에서 카드는 독립적인 버전 관리가 적용된 두 가지 주요 구성요소에 의해 렌더링됩니다. 앱 카드가 모든 기기에서 올바르게 작동하도록 하려면 이 기본 아키텍처를 이해하는 것이 중요합니다.

  • Jetpack 카드 관련 라이브러리: Wear 카드 및 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 렌더러 업데이트가 Play 스토어 또는 시스템 업데이트를 통해 제공됩니다. 특정 렌더러 버전을 강제로 설치할 수는 없습니다.)

Android 스튜디오의 카드 미리보기 기능은 코드가 종속되는 Jetpack ProtoLayout 라이브러리에 삽입된 렌더러를 사용하므로 카드를 테스트할 때 다른 Jetpack 라이브러리 버전에 종속되는 것도 한 가지 방법입니다.

Jetpack 라이브러리 업그레이드

Jetpack Tile 라이브러리를 업데이트하여 카드가 시스템과 원활하게 통합되도록 하는 UI 변경사항을 비롯한 최신 개선사항을 활용하세요.

Tiles 1.2 / ProtoLayout 1.0으로 이전

버전 1.2부터 대부분의 Tiles Layout 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()로