Version Code: qué es, identificador numérico y actualizaciones

Qué es el Version Code en Android

Version Code es un número entero de tipo Integer que se asigna a cada compilación de una aplicación Android. A diferencia del Version Name, el Version Code no se muestra al usuario y lo utilizan exclusivamente el sistema operativo y Google Play para comparar versiones al instalar actualizaciones.

Formato del Version Code

Version Code debe ser un número entero positivo en el rango de 1 a 2100000000. Cada compilación posterior debe tener un Version Code estrictamente mayor que el anterior. Si un desarrollador publicó una compilación con Version Code 5, la siguiente publicación puede usar 6, 7 o cualquier número mayor que 5, pero no 4 ni 5 nuevamente.

Historia del origen

Google introdujo la separación entre Version Code y Version Name con el lanzamiento del SDK de Android en 2007. Version Code fue concebido como un identificador de máquina para la comparación automática de versiones, mientras que Version Name se concibió como una etiqueta legible para humanos. Esta separación permite al desarrollador nombrar la versión como desee, manteniendo un orden estricto de actualizaciones mediante el código numérico.

Cómo funciona el versionado mediante Version Code

El mecanismo de comparación del Version Code está integrado en el sistema operativo Android y en Google Play. Con cada publicación, Google Play verifica que el Version Code de la nueva compilación sea mayor que el código de la versión instalada. Si no se cumple la condición, la publicación se rechaza con un error.

Proceso de verificación de actualizaciones

Cuando un dispositivo se conecta a Google Play para buscar actualizaciones, el servidor compara el Version Code de la aplicación instalada con el máximo disponible en la tienda. Si el código en el servidor es mayor, se inicia la descarga e instalación de la actualización. El usuario ve el Version Name indicado por el desarrollador, pero la decisión de actualizar se toma en base al Version Code.

Incremento del Version Code

Los desarrolladores aplican diferentes estrategias para incrementar el Version Code. La más simple es aumentar en 1 con cada compilación. Para pipelines CI/CD se suele usar un timestamp o el número de compilación: 2026070301 (año-mes-día-número). Es importante que el código aumente monótonamente y no se repita entre diferentes compilaciones y canales de Google Play.

• Incremento monótono — aumento de 1 por cada commit en la rama de lanzamiento
• Formato timestamp — 20260703 para compilaciones diarias, 2026070301 para varias al día
• SemVer en números — 100010000 para la versión 1.1.0 (major 1, minor 1, patch 0)
• Número de compilación — uso de BUILD_NUMBER del sistema CI (Jenkins, GitHub Actions)

Diferencias entre Version Code y Version Name

Version Code y Version Name son dos campos independientes en build.gradle que cumplen funciones diferentes. Version Code es un identificador interno para el sistema, Version Name es una etiqueta de marketing para el usuario. Pueden cambiar independientemente uno del otro.

Version Name para el usuario

Version Name es una cadena que se muestra en la configuración de la aplicación, en Google Play y en los diálogos de actualización. El desarrollador puede especificar cualquier formato: 1.0.0, 2.3.1-beta, 3.0-rc1. Version Name no se usa para comparar versiones textuales — Google Play siempre se basa en el Version Code.

Escenarios de divergencia

Es posible una situación donde el Version Code aumenta mientras que el Version Name permanece igual. Por ejemplo, si un desarrollador corrige un error crítico en una compilación hotfix sin cambiar la funcionalidad. El Version Name sigue siendo 2.0.0, mientras que el Version Code cambia de 5 a 6. Google Play manejará correctamente dicha actualización.

// Ejemplo: el version name no cambia, el código aumenta
android {
    defaultConfig {
        versionCode 6  // Era 5 — hotfix sin nuevas funciones
        versionName "2.0.0"  // No cambió
    }
}

// Verificación de versiones en runtime
val code = BuildConfig.VERSION_CODE
val name = BuildConfig.VERSION_NAME
println("Code: $code, Name: $name")

Configuración del Version Code en build.gradle

La configuración del Version Code se realiza en el archivo build.gradle del módulo de la aplicación. El campo versionCode acepta un número entero y forma parte del bloque defaultConfig. Para diferentes compilaciones de variantes (flavors), se pueden establecer valores personalizados mediante el campo versionCode en la configuración del producto.

Configuración 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
        }
    }
}

Los Product flavors permiten usar diferentes Version Code para distintas configuraciones: versión demo, versión separada para tabletas. Si se usan flavors en el proyecto, el Version Code final se compone del número base y el incremento específico del flavor. Google Play rastrea cada combinación de forma independiente.

Automatización del incremento mediante CI

En los pipelines CI/CD (GitHub Actions, GitLab CI, Jenkins), el Version Code a menudo se genera automáticamente basándose en el número de compilación o la fecha. Esto elimina el error humano en las actualizaciones manuales. El script lee el Version Code actual de build.gradle, lo incrementa y lo escribe de nuevo antes de iniciar la compilación.

// Incremento automático del 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 del Version Code para publicar en Google Play

Google Play tiene reglas estrictas para el Version Code al publicar y actualizar aplicaciones. Violar estas reglas provoca el rechazo de la compilación o la imposibilidad de lanzar una actualización. El desarrollador debe comprender las limitaciones y las estrategias de gestión del código en todas las etapas del ciclo de vida.

Regla de incremento monótono

Google Play no permite subir un APK o AAB cuyo Version Code sea menor o igual al publicado actualmente. Esta regla se aplica a cada canal (production, beta, alpha) de forma independiente. Si en production se ha subido una compilación con Version Code 10 y en alpha una con código 5, el canal alpha puede actualizarse a 6, 7, 8 o 9, pero production permanece en 10.

Migración entre canales

Al promover una compilación de alpha a beta y luego a production, el Version Code debe aumentar en cada etapa. Si la versión alpha tiene código 10, beta puede usar 11 y production 12. No se puede lanzar a production una compilación con código 10 si alpha ya está usando 10, incluso si production aún no lo ha visto.

• Incremento monótono — cada compilación en un canal tiene un Version Code mayor que la anterior en el mismo canal
• Conciencia entre canales — al promover entre canales, el Version Code aumenta secuencialmente
• Pruebas internas — el canal de pruebas internas usa las mismas reglas de monotonicidad
• Múltiples APK — el formato antiguo de publicación requería un Version Code único para cada APK

Errores al indicar el Version Code

El error más común es la coincidencia del Version Code en diferentes compilaciones subidas al mismo canal. Google Play devuelve el error APK_VERSION_CODE_ALREADY_EXISTS. Otro error es superar el valor máximo de 2100000000, lo que provoca un fallo de compilación. Para evitar conflictos, use la generación automática de código en su sistema CI vinculada al número de compilación o a la fecha de compilación.

Los desarrolladores también suelen cometer el error de no incrementar el Version Code al compilar un hotfix para un canal alternativo. Si production tiene código 15 y el canal alpha se quedó en 14, al promover alpha a production, Google Play rechazará la compilación porque su código es menor que el código actual de production. Supervise la monotonicidad del código en todos los canales simultáneamente — para ello, es conveniente usar un único archivo version.properties del cual todos los canales lean el valor actual.