O controle de versões é um componente essencial da estratégia de upgrade e manutenção do app. O controle de versões é importante porque:
- os usuários precisam ter informações específicas sobre a versão do app instalada no dispositivo e as versões de upgrade disponíveis para instalação;
- outros apps, inclusive aqueles publicados como um pacote, precisam consultar o sistema para saber a versão do seu app, a fim de determinar a compatibilidade e identificar dependências;
- Os serviços em que você publica seus apps também podem precisar consultar a versão do app para que ela possa ser mostrada aos usuários. Os serviços de publicação também podem precisar conferir a versão do app para determinar a compatibilidade e estabelecer relações de upgrade/downgrade.
O sistema Android usa as informações da versão do seu app para evitar downgrades. O sistema não usa informações da versão do app para aplicar restrições a upgrades ou à compatibilidade de apps de terceiros. Em caso de restrições da versão, é o app que precisa aplicá-las e informar o usuário sobre elas.
O sistema Android aplica a compatibilidade da versão do sistema, conforme determinada
pela configuração minSdk
nos arquivos de build. Essa configuração
permite que um app especifique a API mínima do sistema com que é compatível.
Para saber mais sobre os requisitos de API,
consulte Especificar requisitos de nível da API.
Os requisitos de controle de versões variam de acordo com o projeto. No entanto, muitos desenvolvedores consideram o controle de versões semântico uma boa base para uma estratégia de controle de versões.
Definir informações da versão do app
Para determinar as informações da versão do seu app, defina valores para as configurações da versão nos arquivos de build do 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" ... } ... } ...
Configurações da versão
Defina os valores das duas configurações da versão disponíveis: versionCode
e
versionName
.
versionCode
- Um número inteiro positivo usado como um número interno da versão.
Esse número ajuda a determinar se uma versão é mais recente
que outra. Números maiores indicam versões mais recentes. Esse
não é o número da versão mostrado aos usuários, mas
é definido pela
configuração
versionName
. O sistema Android usa o valorversionCode
para proteger contra downgrades, evitando que o usuário instale um APK com umversionCode
menor que o da versão instalada no dispositivo.O valor é um número inteiro positivo. Assim, outros apps podem avaliá-lo programaticamente, por exemplo, para verificar uma relação de upgrade ou downgrade. É possível definir o valor como qualquer número inteiro positivo. No entanto, verifique se cada versão sucessiva do app usa um valor maior.
Observação: o maior valor de
versionCode
permitido pelo Google Play é 2100000000.Não é possível fazer upload de um APK na Play Store com um
versionCode
já usado em uma versão anterior.Observação: em algumas situações, convém fazer upload de uma versão do app com um
versionCode
menor que o da versão mais recente. Por exemplo, se você estiver publicando vários APKs, talvez tenha intervalos deversionCode
predefinidos para APKs específicos. Para saber mais sobre como atribuir valores deversionCode
para vários APKs, consulte Atribuir códigos de versão.Normalmente, a primeira versão do app é lançada com o
versionCode
definido como 1. Nas versões subsequentes, esse valor sempre aumenta, independente da versão ser um lançamento principal ou secundário. Isso significa que o valor deversionCode
não é necessariamente igual à versão de lançamento do app visível para o usuário. Apps e serviços de publicação não podem mostrar esse valor da versão aos usuários. versionName
Uma string usada como o número da versão mostrado aos usuários. Essa configuração pode ser especificada como uma string bruta ou uma referência a um recurso de string.
O valor é uma string, assim você pode descrever a versão do app como uma string <major>.<minor>.<point> ou como qualquer outro tipo de identificador de versão absoluto ou relativo. O
versionName
é o único valor mostrado aos usuários.
Definir valores de versões
Você pode definir valores padrão para essas configurações incluindo-os no bloco
defaultConfig {}
, aninhado dentro do bloco android {}
do arquivo build.gradle
ou build.gradle.kts
do seu módulo. É possível modificar
esses valores padrão para diferentes versões do app definindo valores
separados para tipos de build ou variações de produto individuais. O arquivo a seguir mostra as
configurações de versionCode
e versionName
no bloco defaultConfig {}
, bem como no bloco productFlavors {}
.
Esses valores são mesclados no arquivo de manifesto do app durante o processo de build.
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") { ... } } }
No bloco defaultConfig {}
deste exemplo, o valor versionCode
indica que o APK atual contém a segunda versão do app, e a string versionName
especifica que ela aparecerá para os usuários como versão 1.1. Este arquivo também define duas variações de produto,
"demo" (demonstração) e "full" (completa). Como a variação "demo" do produto define versionName
como
"1.1-demo", o build "demo" usa este versionName
em vez do valor padrão.
O bloco de variação do produto "full" não define versionName
, portanto,
o valor padrão "1.1" é usado.
Observação: se o app definir a versão diretamente no
elemento <manifest>
, os valores da versão no arquivo
de build do Gradle vão modificar as configurações no manifesto. Além disso, a definição dessas
configurações nos arquivos de build do Gradle permite que você especifique valores diferentes para
versões diferentes do seu app. Para ter maior flexibilidade e evitar
possíveis substituições quando o manifesto for mesclado, remova esses
atributos do elemento <manifest>
e defina suas
configurações de versão nos arquivos de build do Gradle.
O framework do Android fornece uma API para que você possa consultar o sistema
em busca de informações sobre a versão do seu app. Para informações de versão,
use o método
PackageManager.getPackageInfo(java.lang.String, int)
.
Especificar requisitos de nível de API
Se o app exigir uma versão mínima específica da plataforma
Android, você poderá especificar esse requisito de versão como configurações de nível de API no
arquivo build.gradle
ou build.gradle.kts
do app. Durante o processo de build, essas
configurações são mescladas no arquivo de manifesto do app. A especificação de requisitos de
nível da API garante que o app seja instalado apenas em dispositivos que utilizam
uma versão compatível da plataforma Android.
Observação: se você especificar requisitos de nível da API diretamente no
arquivo de manifesto do app, as configurações correspondentes nos arquivos de build
vão modificar as configurações do arquivo de manifesto. Além disso, a definição dessas
configurações nos arquivos de build do Gradle permite que você especifique valores diferentes para
versões diferentes do app. Para maior flexibilidade e evitar
possíveis substituições quando o manifesto for mesclado, remova esses
atributos do elemento <uses-sdk>
e defina suas configurações de nível
da API nos arquivos de build do Gradle.
Existem duas configurações de nível de API:
minSdk
: a versão mínima da plataforma Android em que o app será executado, especificada pelo identificador do nível da API da plataforma.targetSdk
: o nível da API para que o app foi projetado. Em alguns casos, isso permite que o app use elementos do manifesto ou comportamentos definidos no nível da API de destino em vez de ser restringido a usar somente aqueles definidos para o nível da API mínimo.
Para especificar os requisitos de nível da API padrão em um arquivo build.gradle
ou
build.gradle.kts
, adicione uma ou mais configurações de nível de API ao
bloco defaultConfig{}
, aninhado dentro do bloco android {}
. Você também pode
substituir esses valores padrão para versões diferentes
do app adicionando as configurações aos tipos de build ou variações de produto.
O seguinte arquivo especifica as configurações
minSdk
e targetSdk
padrão no bloco
defaultConfig {}
e substitui minSdk
para uma variação de produto.
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 } } }
Ao preparar a instalação do app, o sistema verifica o valor dessas
configurações e as compara à versão do sistema. Se o valor de
minSdk
for maior que o da versão do sistema,
a instalação do app será evitada.
Se você não especificar essas configurações, o sistema vai presumir que o app é
compatível com todas as versões da plataforma. Isso equivale a definir minSdk
como
1
.
Para mais informações, consulte O que é o nível da API?. Para ver as configurações de build do Gradle, consulte Configurar variantes de build.