Version Name: esencia, significado del parámetro y configuración

Qué es Version Name

Version Name es una cadena semántica que identifica la versión de la aplicación para el usuario. A diferencia de los identificadores técnicos de compilación, este parámetro tiene una carga significativa: el usuario puede evaluar cuánto difiere una nueva actualización de la anterior.

Version Name se muestra en la tarjeta de la aplicación en Google Play y App Store, en la sección "Acerca de la aplicación" en el dispositivo, así como en los diálogos de actualización del sistema. Los desarrolladores lo especifican en los archivos de configuración del proyecto antes de compilar la versión de lanzamiento.

Según Semantic Versioning 2.0 (2023), el formato Major.Minor.Patch se utiliza en el 78% de las aplicaciones móviles. La versión principal cambia con cambios incompatibles en la API, la versión menor con la adición de funcionalidad y el parche con la corrección de errores.

Use Version Name para comunicarse con el usuario: debe comprender de inmediato qué tan grande es la actualización que se le ofrece — principal, menor o correctiva.

Estructura de la versión semántica

La versión semántica consta de tres números separados por puntos: Major.Minor.Patch. Cada uno de estos componentes es responsable de un nivel específico de cambios en la aplicación.

La versión principal (Major) aumenta cuando se introducen cambios radicales que rompen la compatibilidad hacia atrás. La versión menor (Minor) agrega nueva funcionalidad sin romper la existente. El parche (Patch) contiene solo correcciones de errores.

Por ejemplo, la versión 3.2.1 significa: tercera versión principal, segunda actualización menor, primer parche. Este sistema es comprensible tanto para desarrolladores como para usuarios.

Dónde se muestra Version Name

Version Name es visible para el usuario en varios lugares clave. En la tienda de aplicaciones, aparece en el encabezado de la tarjeta de la aplicación y en la lista de actualizaciones. En el dispositivo, aparece en la configuración del sistema en la sección "Acerca de la aplicación".

En Google Play, Version Name se muestra debajo del nombre de la aplicación e influye en la decisión del usuario de actualizar. En App Store, la cadena de versión se muestra en el mismo lugar al ver la página de la aplicación.

Según una investigación de Apptentive (2024), el 67% de los usuarios verifican la versión de la aplicación antes de actualizar, y una semántica clara aumenta la conversión de instalación en un 23%.

Version Name en Android

En Android, Version Name se define con el parámetro versionName en el archivo build.gradle (a nivel de módulo). Este parámetro es una cadena y puede contener cualquier carácter, incluyendo puntos, guiones y letras.

El parámetro se declara dentro del bloque android.defaultConfig junto con el parámetro obligatorio versionCode. Android no impone restricciones sobre el formato de la cadena, pero Google Play recomienda usar el formato semántico.

Según Android Developers (2025), Google Play usa versionName para mostrarlo en la interfaz de la tienda, pero no analiza su contenido mediante programación — solo versionCode afecta la lógica de actualización.

Especifique Version Name en el formato Major.Minor.Patch y sincronícelo con la etiqueta en el sistema de control de versiones para una identificación inequívoca del lanzamiento.

Características de versionName en Gradle

Gradle permite definir versionName estáticamente en build.gradle o dinámicamente mediante scripts de compilación. La generación dinámica es útil para compilaciones nocturnas automáticas y pipelines de CI/CD.

En build.gradle, se pueden usar variables de entorno, parámetros de línea de comandos o llamadas a scripts de shell para formar versionName. Un enfoque típico es leer la versión desde un archivo version.properties.

Esta flexibilidad permite a los equipos automatizar el proceso de versionado y eliminar el error humano durante la preparación del lanzamiento.

Version Name en iOS

En iOS, Version Name se define con la clave CFBundleShortVersionString en el archivo Info.plist. Este es un parámetro obligatorio para publicar una aplicación en App Store y está estrictamente tipificado como cadena.

A diferencia de Android, App Store Connect verifica el formato de Version Name y exige que coincida con un patrón de números separados por puntos. La longitud máxima de la cadena es de 18 caracteres y cada componente de la versión no puede exceder 255.

Según la Documentación para desarrolladores de Apple (2025), CFBundleShortVersionString es utilizado por App Store para mostrar la versión en la interfaz de la tienda y en los diálogos del sistema en el dispositivo del usuario.

Al cargar una compilación en App Store Connect, asegúrese de que Version Name coincida con la versión indicada en los materiales de marketing — esto simplifica la comunicación con los usuarios.

Integración con Xcode

Xcode proporciona una interfaz gráfica para cambiar Version Name en la configuración del destino. El campo "Marketing Version" se encuentra en la pestaña General, en la sección Identity. Los cambios se guardan automáticamente en Info.plist.

Para la automatización, se pueden usar scripts de compilación en Xcode Build Phases o la utilidad agvtool (Apple Generic Version Tool). agvtool permite gestionar versiones desde la línea de comandos y se integra en CI/CD.

Este enfoque es especialmente conveniente al usar fastlane o Jenkins para la compilación y entrega automática de aplicaciones.

Diferencias entre Version Name y Build Number

Version Name y Build Number cumplen diferentes funciones en el proceso de desarrollo. Version Name es una cadena visible para el usuario, mientras que Build Number es un identificador numérico interno que identifica de forma única cada compilación.

Build Number (versionCode en Android, CFBundleVersion en iOS) debe aumentar con cada nueva compilación y las tiendas de aplicaciones lo usan para determinar qué versión es más reciente. Version Name puede permanecer sin cambios en varias compilaciones de la misma versión.

Según la Política de Google Play (2025), dos aplicaciones con el mismo versionCode se consideran la misma versión — versionCode debe ser único para cada APK. Version Name no participa en esta verificación.

Incremente siempre Build Number con cada compilación y cambie Version Name solo cuando cambie la funcionalidad — esto previene conflictos durante la publicación.

Cómo elegir Version Name

La elección de Version Name depende de la estrategia de versionado del equipo. El enfoque más común es el versionado semántico (SemVer), pero existen esquemas alternativos, como el versionado por calendario o por fecha de lanzamiento.

Semantic Versioning 2.0 recomienda el formato Major.Minor.Patch con sufijos opcionales de pre-lanzamiento. Para aplicaciones móviles, también es popular el esquema Major.Minor, donde la versión de parche se omite para simplificar la percepción.

El versionado por calendario (CalVer) usa la fecha de lanzamiento como número de versión — por ejemplo, 25.06 (año y mes). Este enfoque es conveniente para aplicaciones con lanzamientos frecuentes donde la semántica no tiene sentido.

Recomendaciones para elegir un esquema

El versionado semántico es adecuado para aplicaciones con API pública donde la compatibilidad hacia atrás es importante. Los usuarios e integradores entienden qué cambios esperar con las actualizaciones.

El versionado por calendario se elige para aplicaciones donde la actualidad del lanzamiento es más importante que el alcance de los cambios. Por ejemplo, agregadores de noticias o aplicaciones del clima.

El esquema híbrido combina ambos enfoques: Major.Minor.RC, donde RC es el número de compilación para un candidato de lanzamiento específico. Este esquema es conveniente durante pruebas beta activas.

Ejemplos de configuración de Version Name

Los ejemplos de código a continuación muestran cómo definir Version Name en Android e iOS. Para Android se usa Gradle, para iOS — Xcode Build Settings con agvtool.

Configuración de versionName en Android

En Android, la versión se define en el archivo app/build.gradle dentro del bloque defaultConfig. El parámetro versionName acepta un valor de cadena.

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

versionName también se puede leer desde un archivo externo o generarse dinámicamente mediante Gradle Script.

Generación dinámica de versionName

La versión dinámica se forma a partir de las variables de entorno del sistema CI/CD. Esto garantiza que cada compilación reciba el número de versión correcto.

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

android {
    defaultConfig {
        versionName getVersionName()
    }
}

Este enfoque automatiza el versionado y elimina el riesgo de desajuste entre la compilación y la etiqueta en el repositorio.

Configuración de CFBundleShortVersionString en iOS

En iOS, la versión se puede definir a través de Xcode o mediante la línea de comandos usando agvtool.

# Configuración de la versión de marketing
xcrun agvtool new-marketing-version 2.1.0

# Lectura de la versión actual
xcrun agvtool what-marketing-version

agvtool actualiza automáticamente Info.plist y sincroniza la versión entre todos los destinos en el proyecto de Xcode.