Version Name: essência, significado do parâmetro e configuração

O que é Version Name

Version Name é uma string semântica que identifica a versão do aplicativo para o usuário. Ao contrário dos identificadores técnicos de compilação, este parâmetro carrega um significado: o usuário pode avaliar o quanto uma nova atualização difere da anterior.

Version Name é exibido no card do aplicativo no Google Play e App Store, na seção "Sobre o aplicativo" no dispositivo, e nos diálogos de atualização do sistema. Os desenvolvedores o especificam nos arquivos de configuração do projeto antes de compilar a versão de lançamento.

De acordo com Semantic Versioning 2.0 (2023), o formato Major.Minor.Patch é usado em 78% dos aplicativos mobile. A versão principal muda com alterações incompatíveis de API, a versão menor com adição de funcionalidades e o patch com correções de bugs.

Use o Version Name para se comunicar com o usuário: ele deve entender imediatamente o quão significativa é a atualização oferecida — principal, menor ou corretiva.

Estrutura da versão semântica

A versão semântica consiste em três números separados por pontos: Major.Minor.Patch. Cada um desses componentes é responsável por um nível específico de mudanças no aplicativo.

A versão principal (Major) aumenta quando mudanças radicais são introduzidas que quebram a compatibilidade reversa. A versão menor (Minor) adiciona novas funcionalidades sem quebrar as existentes. O patch (Patch) contém apenas correções de bugs.

Por exemplo, a versão 3.2.1 significa: terceira versão principal, segunda atualização menor, primeiro patch. Este sistema é compreensível tanto para desenvolvedores quanto para usuários.

Onde o Version Name é exibido

Version Name fica visível para o usuário em vários locais importantes. Na loja de aplicativos, aparece no cabeçalho do card do aplicativo e na lista de atualizações. No dispositivo, aparece nas configurações do sistema na seção "Sobre o aplicativo".

No Google Play, o Version Name é exibido abaixo do nome do aplicativo e influencia a decisão do usuário de atualizar. Na App Store, a string de versão é exibida no mesmo local ao visualizar a página do aplicativo.

De acordo com a pesquisa da Apptentive (2024), 67% dos usuários verificam a versão do aplicativo antes de atualizar, e uma semântica clara aumenta a conversão de instalação em 23%.

Version Name no Android

No Android, o Version Name é definido pelo parâmetro versionName no arquivo build.gradle (nível do módulo). Este parâmetro é uma string e pode conter qualquer caractere, incluindo pontos, hífens e letras.

O parâmetro é declarado dentro do bloco android.defaultConfig junto com o parâmetro obrigatório versionCode. O Android não impõe restrições ao formato da string, mas o Google Play recomenda usar o formato semântico.

De acordo com Android Developers (2025), o Google Play usa o versionName para exibição na interface da loja, mas não analisa seu conteúdo programaticamente — apenas o versionCode afeta a lógica de atualização.

Especifique o Version Name no formato Major.Minor.Patch e sincronize-o com a tag no sistema de controle de versão para identificação inequívoca do lançamento.

Recursos do versionName no Gradle

Gradle permite definir versionName estaticamente no build.gradle ou dinamicamente através de scripts de compilação. A geração dinâmica é útil para compilações noturnas automáticas e pipelines de CI/CD.

No build.gradle, você pode usar variáveis de ambiente, parâmetros de linha de comando ou chamadas de shell script para formar o versionName. Uma abordagem típica é ler a versão de um arquivo version.properties.

Essa flexibilidade permite que as equipes automatizem o processo de versionamento e eliminem o erro humano durante a preparação do lançamento.

Version Name no iOS

No iOS, o Version Name é definido pela chave CFBundleShortVersionString no arquivo Info.plist. Este é um parâmetro obrigatório para publicar um aplicativo na App Store, e é estritamente tipado como string.

Ao contrário do Android, o App Store Connect verifica o formato do Version Name e exige que corresponda a um padrão de números separados por pontos. O comprimento máximo da string é de 18 caracteres, e cada componente da versão não pode exceder 255.

De acordo com a Documentação do Apple Developer (2025), o CFBundleShortVersionString é usado pela App Store para exibir a versão na interface da loja e nos diálogos do sistema no dispositivo do usuário.

Ao enviar uma compilação para o App Store Connect, certifique-se de que o Version Name corresponda à versão indicada nos materiais de marketing — isso simplifica a comunicação com os usuários.

Integração com Xcode

Xcode fornece uma interface gráfica para alterar o Version Name nas configurações do alvo. O campo "Marketing Version" está localizado na aba General, na seção Identity. As alterações são salvas automaticamente no Info.plist.

Para automação, você pode usar scripts de compilação no Xcode Build Phases ou o utilitário agvtool (Apple Generic Version Tool). O agvtool permite gerenciar versões pela linha de comando e se integra ao CI/CD.

Essa abordagem é especialmente conveniente ao usar fastlane ou Jenkins para compilação e entrega automática de aplicativos.

Diferenças entre Version Name e Build Number

Version Name e Build Number desempenham funções diferentes no processo de desenvolvimento. Version Name é uma string voltada ao usuário, enquanto Build Number é um identificador numérico interno que identifica exclusivamente cada compilação.

Build Number (versionCode no Android, CFBundleVersion no iOS) deve aumentar a cada nova compilação e é usado pelas lojas de aplicativos para determinar qual versão é mais recente. O Version Name pode permanecer inalterado em várias compilações da mesma versão.

De acordo com a Política do Google Play (2025), dois aplicativos com o mesmo versionCode são considerados a mesma versão — o versionCode deve ser único para cada APK. O Version Name não participa desta verificação.

Sempre incremente o Build Number a cada compilação e altere o Version Name apenas quando a funcionalidade mudar — isso evita conflitos durante a publicação.

Como escolher o Version Name

A escolha do Version Name depende da estratégia de versionamento da equipe. A abordagem mais comum é o versionamento semântico (SemVer), mas existem esquemas alternativos, como versionamento por calendário ou por data de lançamento.

Semantic Versioning 2.0 recomenda o formato Major.Minor.Patch com sufixos opcionais de pré-lançamento. Para aplicativos mobile, o esquema Major.Minor também é popular, onde a versão de patch é omitida para simplificar a percepção.

O versionamento por calendário (CalVer) usa a data de lançamento como número de versão — por exemplo, 25.06 (ano e mês). Esta abordagem é conveniente para aplicativos com lançamentos frequentes onde a semântica não faz sentido.

Recomendações para escolher um esquema

O versionamento semântico é adequado para aplicativos com API pública onde a compatibilidade reversa é importante. Usuários e integradores entendem quais mudanças esperar com as atualizações.

O versionamento por calendário é escolhido para aplicativos onde a atualidade do lançamento é mais importante que a abrangência das mudanças. Por exemplo, agregadores de notícias ou aplicativos de clima.

O esquema híbrido combina ambas as abordagens: Major.Minor.RC, onde RC é o número da compilação para um candidato a lançamento específico. Este esquema é conveniente durante testes beta ativos.

Exemplos de configuração do Version Name

Os exemplos de código abaixo mostram como definir o Version Name no Android e iOS. Para Android, usa-se Gradle; para iOS, Xcode Build Settings com agvtool.

Configurando versionName no Android

No Android, a versão é definida no arquivo app/build.gradle dentro do bloco defaultConfig. O parâmetro versionName aceita um valor de string.

android {
    defaultConfig {
        versionCode 3
        versionName "2.1.0"
    }
}

versionName também pode ser lido de um arquivo externo ou gerado dinamicamente usando Gradle Script.

Geração dinâmica de versionName

A versão dinâmica é formada a partir das variáveis de ambiente do sistema CI/CD. Isso garante que cada compilação receba o número de versão correto.

def getVersionName = {
    return System.getenv("VERSION_NAME") ?:
            "2.1.0"
}

android {
    defaultConfig {
        versionName getVersionName()
    }
}

Esta abordagem automatiza o versionamento e elimina o risco de incompatibilidade entre a compilação e a tag no repositório.

Configurando CFBundleShortVersionString no iOS

No iOS, a versão pode ser definida através do Xcode ou pela linha de comando usando agvtool.

# Definindo a versão de marketing
xcrun agvtool new-marketing-version 2.1.0

# Lendo a versão atual
xcrun agvtool what-marketing-version

agvtool atualiza automaticamente o Info.plist e sincroniza a versão entre todos os alvos no projeto Xcode.