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 conseguir 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 ter de 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 de versão do app para aplicar restrições a 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, como 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 compilação do Gradle. Esses valores são mesclados no arquivo de manifesto do app durante o processo de compilação.

Observação: se o app definir a versão do app diretamente no elemento <manifest>, os valores de versão no arquivo de compilação do Gradle modificarão as configurações no manifesto. Além disso, a definição dessas configurações nos arquivos de compilação do Gradle permite especificar valores diferentes para versões distintas do app. Para aumentar a flexibilidade e evitar uma possível substituição na mesclagem do manifesto, remova esses atributos do elemento <manifest> e defina as configurações de versão nos arquivos de compilação do Gradle.

Existem duas configurações, e os valores delas precisam ser sempre definidos:

  • versionCode: um número inteiro positivo usado como 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 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, poderá ter intervalos de 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 de a 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 vista pelo 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: um string usado como número de versão exibido aos usuários. Essa configuração pode ser especificada como um string bruto ou uma referência a um recurso de string.

    O valor é um string, assim você pode descrever a versão do app como um 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-as 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 compilação ou variações de produto individuais. O arquivo build.gradle a seguir mostra as configurações versionCode e versionName nos blocos defaultConfig {} e productFlavors {}.

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

No bloco defaultConfig {} desse exemplo, o valor de versionCode indica que o APK atual contém a segunda versão do app, e o string versionName especifica que ela será exibida aos usuários como versão 1.1. Esse arquivo build.gradle também define duas variações do produto, "demo" e "full". Como a variação "demo" do produto define versionName como "1.1-demo", a compilação "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.

O framework Android oferece uma API que permite consultar o sistema para conseguir informações de versão do app. Para ver as informações de versão, use o método getPackageInfo(java.lang.String, int) do 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 compilação, essas configurações são mescladas no arquivo de manifesto do app. A especificação de requisitos de nível de 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 de API diretamente no arquivo de manifesto do app, as configurações correspondentes nos arquivos de compilação modificarão as configurações do arquivo de manifesto. Além disso, a definição dessas configurações nos arquivos de compilação do Gradle permite especificar valores diferentes para versões distintas do app. Para aumentar a flexibilidade e evitar possíveis modificações na mesclagem do manifesto, remova esses atributos do elemento <uses-sdk> e defina suas configurações de nível de API nos arquivos de compilação 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 de 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 de API de destino em vez de ser restringido a usar somente aqueles definidos para o nível de API mínimo.

Para especificar os requisitos de nível de API padrão 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 modificar esses valores padrão para versões diferentes do app adicionando as configurações aos tipos de compilação ou variações de produto. O arquivo build.gradle a seguir especifica configurações padrão de minSdkVersion e targetSdkVersion no bloco defaultConfig {} e modifica 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 compilação do Gradle, consulte Configurar variações de compilação.