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 consultar a versão do seu app, a fim de determinar a compatibilidade e identificar dependências;
- os serviços usados para publicar seu app também podem precisar consultar a versão para exibi-la 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 de versão de seu app para se proteger contra downgrades. O sistema não usa informações de versão do app para impor restrições sobre upgrades ou compatibilidade de apps de terceiros. Em caso de restrições de 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 minSdkVersion
nos arquivos de compilação. Essa configuração
permite que o app especifique a versão mínima da API de sistema compatível.
Para ver mais informações, consulte Especificar a versão mínima da
API de sistema.
Definir informações de versão do aplicativo
Para determinar as informações de versão do seu app, defina valores para as configurações de versão nos arquivos de build do Gradle. Esses valores são mesclados no arquivo de manifesto do app durante o processo de build.
Observação: se o app definir a versão diretamente no
elemento <manifest>
, os valores da versão no arquivo
de build do Gradle modificarão 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 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.
Existem duas configurações, e os valores delas precisam ser sempre definidos:
-
versionCode
: um número inteiro positivo usado como um número de versão interno. Esse número é usado apenas para determinar se uma versão é mais recente que outra. Números maiores indicam versões mais recentes. Esse não é o número de versão mostrado para os usuários, que é definido pela configuraçãoversionName
descrita abaixo. 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. Você pode definir o valor como qualquer inteiro positivo. No entanto, todo lançamento sucessivo do app precisa usar um valor maior. 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 específicas, é possível que você queira fazer o 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 intervalosversionCode
predefinidos para APKs específicos. Para saber mais sobre como atribuir valores deversionCode
para vários APKs, consulte Compatibilidade com vários APKs.Normalmente, a primeira versão do app é lançada com
versionCode
definido como 1. Nas versões subsequentes, esse valor é sempre aumentado, independentemente da versão ser um lançamento principal ou secundário. Isso significa que o valor deversionCode
não tem necessariamente uma grande semelhança com a versão de lançamento do app visível para o usuário (vejaversionName
abaixo). Apps e serviços de publicação não devem exibir esse valor de versão aos usuários.Alerta: o maior valor de
versionCode
permitido pelo Google Play é 2100000000. -
versionName
: uma string usada como o número da versão exibido 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. A única finalidade de
versionName
é ser exibido aos usuários.
Você pode definir valores padrão para essas configurações incluindo-os no bloco
defaultConfig {}
, aninhado dentro do bloco android {}
do arquivo build.gradle
do 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
build.gradle
a seguir mostra as configurações de versionCode
e versionName
no bloco defaultConfig {}
,
bem como no bloco productFlavors {}
.
android { ... defaultConfig { ... versionCode 2 versionName "1.1" } productFlavors { demo { ... versionName "1.1-demo" } full { ... } } }
No bloco defaultConfig {}
deste exemplo, o valor
versionCode
indica que o APK atual contém a
segunda versão do aplicativo, e a string versionName
especifica
que ela aparecerá para os usuários como versão 1.1. Este arquivo build.gradle
também define duas variações de produto, "demo" 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 de produto "full" não define versionName
, portanto,
o valor padrão "1.1" é usado.
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
getPackageInfo(java.lang.String, int)
de PackageManager
.
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
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
modificarão 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:
minSdkVersion
: a versão mínima da plataforma Android em que o app será executado, especificada pelo identificador do nível da API da plataforma.targetSdkVersion
: especifica o nível da API para o qual 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 requisitos padrão de nível da API em um arquivo build.gradle
,
adicione uma ou mais das configurações acima 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 build.gradle
especifica as configurações
minSdkVersion
e targetSdkVersion
padrão no bloco
defaultConfig {}
e substitui minSdkVersion
para uma variação de produto.
android { ... defaultConfig { ... minSdkVersion 14 targetSdkVersion 24 } productFlavors { main { ... } afterLollipop { ... minSdkVersion 21 } } }
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
minSdkVersion
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 presumirá que o app é compatível com todas as versões de plataforma.
Para ver mais informações, consulte a documentação do elemento de manifesto <uses-sdk>
e o documento
Níveis de API. Para ver as configurações de build do Gradle, consulte Configurar variantes de build.