Controlar versões do seu app

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 valor versionCode para proteger contra downgrades, evitando que o usuário instale um APK com um versionCode 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 de versionCode predefinidos para APKs específicos. Para saber mais sobre como atribuir valores de versionCode 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 de versionCode 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.