앱 버전 지정

버전 관리는 앱 업그레이드와 유지보수 전략에서 중요한 구성요소입니다. 버전 관리가 중요한 이유는 다음과 같습니다.

  • 사용자는 기기에 설치된 앱 버전과 설치할 수 있는 업그레이드 버전에 관한 구체적인 정보를 알아야 합니다.
  • 묶음 형태로 게시하는 앱을 포함한 다른 앱은 시스템에 앱의 버전을 쿼리하여 호환성을 확인하고 종속 항목을 파악해야 합니다.
  • 앱을 게시하는 서비스는 사용자에게 버전을 표시할 수 있도록 앱에 버전을 쿼리해야 할 수도 있습니다. 게시 서비스에서는 앱 버전을 검사하여 호환성을 확인하고 업그레이드/다운그레이드 관계를 설정해야 할 수도 있습니다.

Android 시스템에서는 다운그레이드를 방지하기 위해 앱 버전 정보를 사용합니다. 시스템은 앱 버전 정보를 사용하여 서드 파티 앱의 업그레이드 또는 호환성에 제한을 가하지 않습니다. 앱은 버전 제한을 적용해야 하며 버전 제한에 관해 사용자에게 알립니다.

Android 시스템은 빌드 파일의 minSdk 설정에 명시된 대로 시스템 버전 호환성을 적용합니다. 이 설정을 통해 앱은 호환되는 최소 시스템 API를 지정할 수 있습니다. API 요구사항에 관한 자세한 내용은 API 수준 요구사항 지정을 참고하세요.

버전 관리 요구사항은 프로젝트마다 다릅니다. 그러나 많은 개발자가 시맨틱 버전 관리를 버전 관리 전략에 적합하다고 간주합니다.

앱 버전 정보 설정

앱의 버전 정보를 정의하려면 Gradle 빌드 파일에 버전 설정을 위한 값을 설정해야 합니다.

Groovy

    android {
      namespace 'com.example.testapp'
      compileSdk 33

      defaultConfig {
          applicationId "com.example.testapp"
          minSdk 24
          targetSdk 33
          versionCode 1
          versionName "1.0"
          ...
      }
      ...
    }
    ...
    

Kotlin

    android {
      namespace = "com.example.testapp"
      compileSdk = 33

      defaultConfig {
          applicationId = "com.example.testapp"
          minSdk = 24
          targetSdk = 33
          versionCode = 1
          versionName = "1.0"
          ...
      }
      ...
    }
    ...
      

버전 설정

사용 가능한 두 버전 설정(versionCode, versionName)의 값을 모두 정의합니다.

versionCode
양의 정수이며, 내부 버전 번호로 사용됩니다. 이 번호는 한 버전이 다른 버전보다 최신인지를 판단하는 데 도움이 되며, 번호가 높을수록 최신 버전임을 나타냅니다. 사용자에게 표시되는 버전 번호가 아닙니다. 사용자에게 표시되는 번호는 versionName 설정으로 지정됩니다. Android 시스템은 versionCode 값을 사용하여 versionCode가 현재 기기에 설치되어 있는 버전보다 낮은 APK를 사용자가 설치하지 못하게 함으로써 다운그레이드를 방지합니다.

이 값은 양의 정수이므로 다른 앱이 예를 들어, 업그레이드나 다운그레이드 관계를 확인할 때 프로그래매틱 방식으로 이 값을 평가할 수 있습니다. 이 값은 어떤 양의 정수로도 설정할 수 있습니다. 그러나 앱의 후속 버전이 출시될 때마다 더 큰 값을 사용해야 합니다.

참고: Google Play에서 versionCode로 허용하는 가장 큰 값은 2100000000입니다.

이미 이전 버전에 사용한 versionCode로는 APK를 Play 스토어에 업로드할 수 없습니다.

참고: 경우에 따라 최신 버전보다 낮은 versionCode로 앱 버전을 업로드해야 할 수도 있습니다. 예를 들어 여러 APK를 게시하는 경우 특정 APK에 versionCode 범위를 사전 설정할 수 있습니다. 여러 APK의 versionCode 값을 할당하는 방법에 관한 자세한 내용은 버전 코드 할당을 참고하세요.

일반적으로 앱의 첫 번째 버전은 versionCode를 1로 설정하여 출시하고, 메이저 출시 버전이든 마이너 출시 버전이든 관계없이 각 버전마다 일정하게 값을 증가시킵니다. 즉, versionCode 값이 사용자에게 표시되는 앱 출시 버전과 꼭 동일하지는 않습니다. 앱 및 게시 서비스는 사용자에게 이 버전 값을 표시해서는 안 됩니다.

versionName

사용자에게 표시되는 버전 번호로 사용되는 문자열입니다. 이 설정은 원시 문자열이나 문자열 리소스의 참조로 지정할 수 있습니다.

값은 문자열로서, <major>.<minor>.<point> 문자열이나 다른 유형의 절대 또는 상대 버전 식별자로 앱 버전을 설명할 수 있습니다. versionName이 사용자에게 표시되는 유일한 값입니다.

버전 값 정의

모듈의 build.gradle 또는 build.gradle.kts 파일에서 android {} 블록 내에 중첩되어 있는 defaultConfig {} 블록에 이 설정을 포함하여 이 설정의 기본값을 정의할 수 있습니다. 그런 다음, 개별 빌드 유형 또는 제품 버전별로 별도의 값을 정의하여 여러 앱 버전의 이러한 기본값을 재정의할 수 있습니다. 다음 파일에서는 productFlavors {} 블록과 defaultConfig {} 블록 내에 있는 versionCodeversionName 설정을 보여줍니다.

그러면 이러한 값이 빌드 프로세스 도중에 앱의 매니페스트 파일로 병합됩니다.

Groovy

    android {
        ...
        defaultConfig {
            ...
            versionCode 2
            versionName "1.1"
        }
        productFlavors {
            demo {
                ...
                versionName "1.1-demo"
            }
            full {
                ...
            }
        }
    }
    

Kotlin

    android {
        ...
        defaultConfig {
            ...
            versionCode = 2
            versionName = "1.1"
        }
        productFlavors {
            create("demo") {
                ...
                versionName = "1.1-demo"
            }
            create("full") {
                ...
            }
        }
    }
    

이 예의 defaultConfig {} 블록에서 versionCode 값은 현재 APK에 앱의 두 번째 출시 버전이 포함되어 있다는 것을 나타내고 versionName 문자열은 사용자에게 버전이 1.1로 표시되도록 지정합니다. 이 파일에서는 두 제품 버전 'demo' 및 'full'도 정의합니다. 'demo' 제품 버전에서 versionName이 '1.1-demo'로 정의되어 있으므로 'demo' 빌드는 기본값 대신 이 versionName을 사용합니다. 'full' 제품 버전 블록에서는 versionName이 정의되어 있지 않으므로 기본값 '1.1'을 사용합니다.

참고: 앱이 <manifest> 요소에서 직접 앱 버전을 정의하는 경우 Gradle 빌드 파일의 버전 값이 매니페스트의 설정을 재정의합니다. 또한, Gradle 빌드 파일에서 이러한 설정을 정의하면 앱의 여러 버전별로 서로 다른 값을 지정할 수 있습니다. 유연성을 강화하고 매니페스트가 병합될 때 이러한 설정을 덮어쓰는 것을 방지하려면 <manifest> 요소에서 이러한 속성을 삭제하고 Gradle 빌드 파일에서 버전 설정을 대신 정의합니다.

Android 프레임워크에서는 시스템에 앱 관련 버전 정보를 쿼리하는 데 사용할 수 있는 API를 제공합니다. 버전 정보를 가져오려면 PackageManager.getPackageInfo(java.lang.String, int) 메서드를 사용하세요.

API 수준 요구사항 지정

앱이 Android 플랫폼의 특정 최소 버전을 요구하는 경우 앱의 build.gradle 또는 build.gradle.kts 파일에서 이러한 버전 요구사항을 API 수준 설정으로 지정할 수 있습니다. 이러한 설정은 빌드 프로세스 동안 앱의 매니페스트 파일에 병합됩니다. API 수준 요구사항을 지정하면 호환되는 Android 플랫폼 버전을 실행하는 기기에만 앱이 설치될 수 있도록 합니다.

참고: 앱의 매니페스트 파일에서 직접 API 수준 요구사항을 지정하면 빌드 파일에서 이에 상응하는 설정이 매니페스트 파일의 설정을 재정의합니다. 또한, Gradle 빌드 파일에서 이러한 설정을 정의하면 앱의 여러 버전별로 서로 다른 값을 지정할 수 있습니다. 유연성을 강화하고 매니페스트가 병합될 때 이러한 설정을 덮어쓰는 것을 방지하려면 <uses-sdk> 요소에서 이러한 속성을 삭제하고 Gradle 빌드 파일에서 API 수준 설정을 대신 정의합니다.

두 가지 API 수준 설정을 사용할 수 있습니다.

  • minSdk: 앱이 실행되는 Android 플랫폼의 최소 버전이며, 플랫폼의 API 수준 식별자에 의해 지정됩니다.
  • targetSdk: 앱이 실행되도록 설계된 API 수준입니다. 경우에 따라 최소 API 수준에 정의된 것만 사용하도록 제한하기보다는 앱이 대상 API 수준에서 정의된 매니페스트 요소나 동작을 사용하도록 허용합니다.

build.gradle 또는 build.gradle.kts 파일에서 기본 API 수준 요구사항을 지정하려면 android {} 블록 내에 중첩되어 있는 defaultConfig{} 블록에 하나 이상의 API 수준 설정을 추가합니다. 또한 이 설정을 빌드 유형이나 제품 버전에 추가하여 여러 앱 버전의 이러한 기본값을 재정의할 수도 있습니다.

다음 파일에서는 defaultConfig {} 블록에서 기본 minSdktargetSdk 설정을 지정하고 한 제품 버전의 minSdk를 재정의합니다.

Groovy

android {
    ...
    defaultConfig {
        ...
        minSdk 21
        targetSdk 33
    }
    productFlavors {
        main {
            ...
        }
        afterNougat {
            ...
            minSdk 24
        }
    }
}

Kotlin

android {
    ...
    defaultConfig {
        ...
        minSdk = 21
        targetSdk = 33
    }
    productFlavors {
        create("main") {
            ...
        }
        create("afterNougat") {
            ...
            minSdk = 24
        }
    }
}

앱 설치를 준비할 때 시스템은 이러한 설정 값을 확인하고 시스템 버전과 비교합니다. minSdk 값이 시스템 버전보다 크면 시스템에서 앱 설치가 차단됩니다.

이러한 설정을 지정하지 않으면 시스템에서는 앱이 모든 플랫폼 버전과 호환되는 것으로 간주합니다. 이는 minSdk를 다음과 같이 설정하는 것과 같습니다. 1

자세한 내용은 API 수준이란 무엇인가요?를 참고하세요. Gradle 빌드 설정의 경우 빌드 변형 구성을 참고하세요.