Controlar versões do 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 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ção versionName descrita abaixo. 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. 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 intervalos versionCode predefinidos para APKs específicos. Para saber mais sobre como atribuir valores de versionCode 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 de versionCode não tem necessariamente uma grande semelhança com a versão de lançamento do app visível para o usuário (veja versionName 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 {}.

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 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.

Groovy

android {
    ...
    defaultConfig {
        ...
        minSdkVersion 14
        targetSdkVersion 24
    }
    productFlavors {
        main {
            ...
        }
        afterLollipop {
            ...
            minSdkVersion 21
        }
    }
}

Kotlin

android {
    ...
    defaultConfig {
        ...
        minSdkVersion(14)
        targetSdkVersion(24)
    }
    productFlavors {
        create("main") {
          ...
        }
        create("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.