Save the date! Android Dev Summit is coming to Mountain View, CA on November 7-8, 2018.

Controlar versões de aplicativos

O controle de versões é um componente essencial da estratégia de upgrade e manutenção de um aplicativo. O controle de versões é importante porque:

  • Os usuários precisam ter informações específicas sobre a versão do aplicativo instalada no dispositivo e as versões de upgrade disponíveis para instalação.
  • Outros aplicativos, inclusive os publicados como um pacote, precisam consultar o sistema para obter a versão do aplicativo, para determinar a compatibilidade e identificar dependências.
  • Os serviços usados para publicar o aplicativo também podem precisar consultar a versão do aplicativo para exibi-la aos usuários. Os serviços de publicação também podem ter de conferir a versão do aplicativo para determinar a compatibilidade e estabelecer relações de upgrade/downgrade.

O sistema Android não usa informações de versão do aplicativo para aplicar restrições a upgrades, downgrades ou compatibilidade de aplicativos de terceiros. Em vez disso, você (o desenvolvedor) é o responsável por aplicar as restrições de versão no aplicativo ou informar os usuários das restrições e limitações da versão. No entanto, 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 um aplicativo especifique a versão mínima da API de sistema com a qual ele é compatível. Para obter mais informações, consulte Especificação da versão mínima da API de sistema.

Definir informações de versão do aplicativo

Para definir as informações de versão do aplicativo, 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 aplicativo durante o processo de compilação.

Observação: se o aplicativo definir a versão 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 aplicativo. Para aumentar a flexibilidade e evitar uma possível substituição na mesclagem do manifesto, você deve remover esses atributos do elemento <manifest> e definir as configurações de versão nos arquivos de compilação do Gradle.

Existem duas configurações, e seus valores devem sempre ser definidos:

  • versionCode – um inteiro 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 aos usuários, que é definido pela configuração versionName, descrita abaixo.

    O valor é um inteiro, permitindo que outros aplicativos possam avaliá-lo programaticamente como, por exemplo, para verificar um relacionamento de upgrade ou downgrade. Você pode definir o valor como qualquer inteiro. No entanto, assegure que cada lançamento subsequente do aplicativo use um valor maior. O sistema não impõe esse comportamento, mas o aumento do valor nas versões subsequentes é obrigatório.

    Normalmente, a primeira versão do aplicativo é lançada com versionCode definido como 1. Nas versões subsequentes, aumente sempre esse valor, 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 aplicativo vista pelo usuário (veja versionName, abaixo). Aplicativos e serviços de publicação não devem exibir esta versão aos usuários.

    Aviso: o maior valor de versionCode permitido pelo Google Play é 2100000000.

  • versionName – um string usado como número de versão exibido aos usuários. Pode-se especificar essa configuração como um string bruto ou uma referência a um recurso de string.

    O valor é um string, permitindo que você descreva a versão do aplicativo como um string <principal>.<secundária>.<pontual> 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. Esses valores padrão podem ser modificados para as diferentes versões do aplicativo definindo valores separados para tipos de compilação ou variações de produto individuais. O arquivo build.gradle mostra as configurações versionCode e versionName no bloco defaultConfig {} e no bloco 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 aplicativo, 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 esse 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" será usado.

O framework Android oferece uma API que permite consultar o sistema para obter informações de versão do aplicativo. Para obter as informações da versão, use o método getPackageInfo(java.lang.String, int) de PackageManager.

Observação: ao usar Instant Run, o Android Studio define automaticamente versionCode como MAXINT e versionName como "INSTANTRUN".

Especificar requisitos de nível de API

Se o aplicativo 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 aplicativo. Durante o processo de compilação essas configurações são mescladas no arquivo de manifesto do aplicativo. A especificação de requisitos de nível de API garante que o aplicativo seja instalado apenas em dispositivos executando 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 aplicativo, as configurações correspondentes dos 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 aplicativo. Para aumentar a flexibilidade e evitar uma possível substituição na mesclagem do manifesto, você deve remover esses atributos do elemento <uses-sdk> e definir as 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 onde o aplicativo será executado, especificada pelo identificador do nível da API da plataforma.
  • targetSdkVersion – especifica o nível de API para o qual o aplicativo foi projetado. Em alguns casos, isso permite que o aplicativo 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 mínimo da API.

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 aplicativo adicionando as configurações para criar tipos de compilação ou variações de produto. O arquivo build.gradle 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 aplicativo, o sistema verifica o valor dessas configurações e as compara à versão do sistema. Se o valor de minSdkVersion for maior que a versão do sistema, este evitará a instalação do aplicativo.

Se você não especificar essas configurações, o sistema considerará o aplicativo compatível com todas as versões de plataforma.

Para obter mais informações, consulte a documentação do elemento de manifesto <uses-sdk> e o documento Níveis de API. Para obter as configurações de compilação do Gradle, consulte Configure variantes de compilação.