Version Code: o que é, identificador numérico e atualizações

O que é Version Code no Android

Version Code é um número inteiro do tipo Integer atribuído a cada compilação de um aplicativo Android. Ao contrário do Version Name, o Version Code não é exibido ao usuário e é usado exclusivamente pelo sistema operacional e pelo Google Play para comparar versões ao instalar atualizações.

Formato do Version Code

Version Code deve ser um número inteiro positivo no intervalo de 1 a 2100000000. Cada compilação subsequente deve ter um Version Code estritamente maior que o anterior. Se um desenvolvedor publicou uma compilação com Version Code 5, a próxima publicação pode usar 6, 7 ou qualquer número maior que 5, mas não 4 nem 5 novamente.

História de origem

O Google introduziu a separação entre Version Code e Version Name com o lançamento do Android SDK em 2007. O Version Code foi concebido como um identificador de máquina para comparação automática de versões, enquanto o Version Name foi criado como um rótulo legível por humanos. Essa separação permite que o desenvolvedor nomeie a versão como desejar, mantendo uma ordem estrita de atualizações através do código numérico.

Como funciona o versionamento através do Version Code

O mecanismo de comparação do Version Code está integrado ao sistema operacional Android e à Google Play Store. A cada publicação, o Google Play verifica se o Version Code da nova compilação é maior que o código da versão instalada. Se a condição não for atendida, a publicação é rejeitada com um erro.

Processo de verificação de atualização

Quando um dispositivo contata o Google Play para verificar atualizações, o servidor compara o Version Code do aplicativo instalado com o máximo disponível na loja. Se o código no servidor for maior, o download e a instalação da atualização são iniciados. O usuário vê o Version Name especificado pelo desenvolvedor, mas a decisão de atualização é tomada com base no Version Code.

Incremento do Version Code

Os desenvolvedores aplicam diferentes estratégias para incrementar o Version Code. A mais simples é aumentar em 1 a cada compilação. Para pipelines CI/CD, frequentemente é usado um timestamp ou número de compilação: 2026070301 (ano-mês-dia-número). É importante que o código aumente monotonicamente e não se repita entre diferentes compilações e canais do Google Play.

• Incremento monotônico — aumento de 1 a cada commit no branch de lançamento
• Formato timestamp — 20260703 para compilações diárias, 2026070301 para várias ao dia
• SemVer em números — 100010000 para versão 1.1.0 (major 1, minor 1, patch 0)
• Número de compilação — uso do BUILD_NUMBER do sistema CI (Jenkins, GitHub Actions)

Diferenças entre Version Code e Version Name

Version Code e Version Name são dois campos independentes no build.gradle que desempenham funções diferentes. O Version Code é um identificador interno para o sistema, o Version Name é um rótulo de marketing para o usuário. Eles podem mudar independentemente um do outro.

Version Name para o usuário

Version Name é uma string exibida nas configurações do aplicativo, no Google Play e nos diálogos de atualização. O desenvolvedor pode especificar qualquer formato: 1.0.0, 2.3.1-beta, 3.0-rc1. O Version Name não é usado para comparação de versões textuais — o Google Play sempre depende do Version Code.

Cenários de divergência

É possível uma situação onde o Version Code aumenta enquanto o Version Name permanece o mesmo. Por exemplo, se um desenvolvedor corrige um bug crítico em uma compilação hotfix sem alterar a funcionalidade. O Version Name permanece 2.0.0, enquanto o Version Code muda de 5 para 6. O Google Play lidará corretamente com essa atualização.

// Exemplo: o version name não muda, o código aumenta
android {
    defaultConfig {
        versionCode 6  // Era 5 — hotfix sem novas funcionalidades
        versionName "2.0.0"  // Não mudou
    }
}

// Verificação de versões em runtime
val code = BuildConfig.VERSION_CODE
val name = BuildConfig.VERSION_NAME
println("Code: $code, Name: $name")

Configuração do Version Code no build.gradle

A configuração do Version Code é feita no arquivo build.gradle do módulo do aplicativo. O campo versionCode aceita um número inteiro e faz parte do bloco defaultConfig. Para diferentes compilações de flavors, valores personalizados podem ser definidos através do campo versionCode na configuração do produto.

Configuração básica

// build.gradle.kts — Kotlin DSL
android {
    defaultConfig {
        applicationId "com.example.app"
        versionCode 15
        versionName "2.1.0"
    }

    flavorDimensions +"version"
    productFlavors {
        create("demo") {
            versionCode 1015
        }
        create("full") {
            versionCode 2015
        }
    }
}

Os Product flavors permitem usar diferentes Version Codes para configurações distintas: versão demo, versão separada para tablets. Se flavors forem usados no projeto, o Version Code final é composto pelo número base e pelo incremento específico do flavor. O Google Play rastreia cada combinação independentemente.

Automação do incremento via CI

Em pipelines CI/CD (GitHub Actions, GitLab CI, Jenkins), o Version Code é frequentemente gerado automaticamente com base no número de compilação ou data. Isso elimina o erro humano durante atualizações manuais. O script lê o Version Code atual do build.gradle, o incrementa e o escreve de volta antes de iniciar a compilação.

// Incremento automático do Version Code
import java.util.Properties
import java.io.FileInputStream

val versionProps = Properties()
versionProps.load(FileInputStream("version.properties"))

val versionCode = versionProps.getProperty("VERSION_CODE").toInt() + 1
versionProps.setProperty("VERSION_CODE", versionCode.toString())

android {
    defaultConfig {
        versionCode = versionCode
    }
}

Particularidades do Version Code para publicação no Google Play

Google Play tem regras rigorosas para o Version Code ao publicar e atualizar aplicativos. Violar essas regras leva à rejeição da compilação ou à impossibilidade de lançar uma atualização. O desenvolvedor precisa entender as limitações e estratégias de gerenciamento de código em todas as etapas do ciclo de vida.

Regra de incremento monotônico

Google Play não permite o upload de um APK ou AAB cujo Version Code seja menor ou igual ao atualmente publicado. Esta regra se aplica a cada canal (production, beta, alpha) independentemente. Se uma compilação com Version Code 10 foi enviada para production e uma com código 5 está em alpha, o canal alpha pode ser atualizado para 6, 7, 8 ou 9, mas production permanece em 10.

Migração entre canais

Ao promover uma compilação de alpha para beta e depois para production, o Version Code deve aumentar em cada etapa. Se a versão alpha tem código 10, beta pode usar 11 e production 12. Você não pode lançar em production uma compilação com código 10 se alpha já está usando 10, mesmo que production ainda não o tenha visto.

• Incremento monotônico — cada compilação em um canal tem um Version Code maior que a anterior no mesmo canal
• Consciência entre canais — ao promover entre canais, o Version Code aumenta sequencialmente
• Testes internos — o canal de testes internos usa as mesmas regras de monotonicidade
• Múltiplos APKs — o formato antigo de publicação exigia um Version Code único para cada APK

Erros ao especificar o Version Code

O erro mais comum é a correspondência do Version Code em diferentes compilações enviadas ao mesmo canal. O Google Play retorna o erro APK_VERSION_CODE_ALREADY_EXISTS. Outro erro é exceder o valor máximo de 2100000000, o que causa uma falha de compilação. Para evitar conflitos, use a geração automática de código em seu sistema CI vinculada ao número de compilação ou data de compilação.

Os desenvolvedores também costumam cometer o erro de não incrementar o Version Code ao compilar uma hotfix para um canal alternativo. Se production tem código 15 e o canal alpha ficou em 14, ao promover alpha para production, o Google Play rejeitará a compilação porque seu código é menor que o código atual de production. Monitore a monotonicidade do código em todos os canais simultaneamente — para isso, é conveniente usar um único arquivo version.properties do qual todos os canais leem o valor atual.