Cómo establecer la versión de tu app

El control de versiones es un componente crítico de la estrategia de actualización y mantenimiento de tu app. Su importancia se debe a lo siguiente:

• Los usuarios deben contar con información específica sobre la versión de la app instalada en sus dispositivos y las versiones de actualización disponibles para su instalación.
• Otras apps, incluidas las que publiques como un paquete, deberán realizar consultas al sistema respecto de la versión de tu app para determinar la compatibilidad e identificar dependencias.
• Es posible que los servicios en los que publicas tus apps también deban consultar sobre su versión antes de mostrarla a los usuarios. Asimismo, puede ser necesario que un servicio de publicación deba verificar la versión de tu app para determinar la compatibilidad y establecer relaciones de cambio a versiones anteriores o posteriores.

El sistema Android usa la información de la versión de tu app para evitar que pase a una versión anterior. El sistema no usa la información sobre la versión de la app para imponer restricciones sobre actualizaciones o compatibilidad de apps de terceros. Tu app debe aplicar todas las restricciones de versiones y debe informar al respecto a los usuarios.

El sistema Android impone la compatibilidad con la versión del sistema, como se expresa en la configuración de minSdk, en los archivos de compilación. Este parámetro de configuración permite que una app especifique el nivel mínimo de API de sistema que admite. Para obtener más información sobre los requisitos de la API, consulta Cómo especificar los requisitos de nivel de API.

Los requisitos del control de versiones varían entre proyectos diferentes. Sin embargo, muchos desarrolladores consideran que el control de versiones semántico es una buena base para una estrategia de control de versiones.

Cómo configurar la información de la versión de la app

Para definir la información de la versión de tu app, establece los valores de configuración de la versión en los archivos de compilación de Gradle:

    android {
      namespace 'com.example.testapp'
      compileSdk 33

      defaultConfig {
          applicationId "com.example.testapp"
          minSdk 24
          targetSdk 33
          versionCode 1
          versionName "1.0"
          ...
      }
      ...
    }
    ...
    

    android {
      namespace = "com.example.testapp"
      compileSdk = 33

      defaultConfig {
          applicationId = "com.example.testapp"
          minSdk = 24
          targetSdk = 33
          versionCode = 1
          versionName = "1.0"
          ...
      }
      ...
    }
    ...
      

Parámetros de configuración de la versión

Define los valores de ambos parámetros disponibles de configuración de la versión: versionCode y versionName.

versionCode

Es el valor entero positivo que se usa como número de versión interna. Este número ayuda a determinar si una versión es más reciente que otra; cuanto más alto es el número, más reciente es la versión. Este no es el número de versión que se muestra a los usuarios, que se establece a través de la configuración versionName. El sistema Android usa el valor versionCode para evitar que la app cambie a una versión inferior, ya que no permite que los usuarios instalen un APK con un versionCode menor que el de la versión instalada actualmente en su dispositivo.

El valor es un entero positivo, por lo que otras apps pueden evaluarlo de manera programática; por ejemplo, para verificar una relación de cambio a versiones anteriores o posteriores. Puedes establecer el valor en cualquier número entero positivo, pero asegúrate de que cada versión sucesiva de tu app use un valor mayor.

Nota: El valor máximo que permite Google Play para versionCode es 2,100,000,000.

No puedes subir un APK a Play Store con un valor de versionCode que ya hayas usado para una versión anterior.

Nota: En algunas situaciones, es posible que quieras subir una versión de tu app con un valor de versionCode inferior al de la versión más reciente. Por ejemplo, si publicas varios APK, es posible que hayas configurado previamente rangos de versionCode para archivos APK específicos. Si deseas obtener más información para asignar valores de versionCode a varios APK, consulta Cómo asignar códigos de versión.

Por lo general, lanzas la primera versión de tu app con el versionCode establecido en 1 y, luego, aumentas el valor de manera continua en cada versión, independientemente de si la versión tiene cambios importantes o menores. Esto significa que el valor de versionCode no necesariamente se parece a la versión de lanzamiento de la app que ve el usuario. Los servicios de apps y publicación no deben mostrar el valor de la versión a los usuarios.

versionName

Es una string que se usa como el número de versión que se muestra a los usuarios. Este parámetro de configuración se puede especificar como una cadena sin procesar o como una referencia a un recurso de cadenas.

El valor es una cadena, por lo que puedes describir la versión de la app como una cadena <major>.<minor>.<point> o como cualquier otro tipo de identificador de versión absoluto o relativo. versionName es el único valor que se muestra a los usuarios.

Cómo definir los valores de la versión

Puedes definir los valores predeterminados para esos parámetros de configuración incluyéndolos en el bloque defaultConfig {}, anidado dentro del bloque android {} del archivo build.gradle o build.gradle.kts de tu módulo. Luego, puedes anular esos valores predeterminados en las diferentes versiones de tu app si defines valores separados para las variantes de producto o los tipos de compilación individuales. En el siguiente archivo, se muestran las opciones de configuraciónversionCode y versionName en los bloques defaultConfig {} y productFlavors {}.

Esos valores se combinan en el archivo del manifiesto de tu app durante el proceso de compilación.

    android {
        ...
        defaultConfig {
            ...
            versionCode 2
            versionName "1.1"
        }
        productFlavors {
            demo {
                ...
                versionName "1.1-demo"
            }
            full {
                ...
            }
        }
    }
    

    android {
        ...
        defaultConfig {
            ...
            versionCode = 2
            versionName = "1.1"
        }
        productFlavors {
            create("demo") {
                ...
                versionName = "1.1-demo"
            }
            create("full") {
                ...
            }
        }
    }
    

En el bloque defaultConfig {} de este ejemplo, el valor versionCode indica que el APK actual contiene la segunda versión de la app, y en la string versionName, se especifica que aparecerá ante los usuarios como versión 1.1. Además, se definen dos variantes de producto: "demo" y "full". Debido a que la variante de producto "demo" define versionName como "1.1-demo", la compilación "demo" usa este versionName en lugar del valor predeterminado. El bloque de variante de producto "full" no define versionName. Por lo tanto, este usa el valor predeterminado de "1.1".

Nota: Si tu app define su versión directamente en el elemento <manifest>, los valores de versión del archivo de compilación de Gradle anularán la configuración del manifiesto. Además, definir esos parámetros de configuración en los archivos de compilación de Gradle te permite especificar valores diferentes para distintas versiones de tu app. Si quieres obtener una mayor flexibilidad y evitar una posible anulación cuando se integre el manifiesto, deberás quitar esos atributos del elemento <manifest> y definir la configuración de tu versión en los archivos de compilación de Gradle.

El framework de Android proporciona una API que te permite hacer consultas al sistema y buscar información de la versión de tu app. Para obtener información de la versión, usa el método PackageManager.getPackageInfo(java.lang.String, int).

Cómo especificar los requisitos de nivel de API

Si tu app requiere una versión mínima específica de la plataforma de Android, puedes especificar ese requisito como una configuración de nivel de API en los archivos build.gradle o build.gradle.kts de la app. Durante el proceso de compilación, se combinan los parámetros de configuración con el archivo del manifiesto de la app. Al especificar los requisitos de nivel de API, garantizas que tu app pueda instalarse únicamente en dispositivos que ejecuten una versión compatible de la plataforma Android.

Nota: Si especificas los requisitos de nivel de API directamente en el archivo de manifiesto de tu app, la configuración correspondiente de los archivos de compilación anulará la del archivo de manifiesto. Además, definir esos parámetros de configuración en los archivos de compilación de Gradle te permite especificar valores diferentes para las distintas versiones de tu app. Quita esos atributos del elemento <uses-sdk> y define la configuración de nivel de API en los archivos de compilación de Gradle para tener mayor flexibilidad y evitar que una configuración anule a otra.

Hay dos parámetros de configuración de nivel de API disponibles:

• minSdk: Es la versión mínima de la plataforma Android en la que podrá ejecutarse la app, especificada por el identificador de nivel de API de la plataforma.
• targetSdk: Especifica el nivel de API en el que la app está diseñada para ejecutarse. En algunos casos, eso permite que la app use elementos del manifiesto o comportamientos definidos en el nivel de API de destino, en vez de limitarse a usar únicamente aquellos definidos por el nivel mínimo de API.

Para especificar los requisitos predeterminados de nivel de API en un archivo build.gradle o build.gradle.kts, agrega uno o más de los parámetros de configuración de nivel de API al bloque defaultConfig{}, anidado dentro del bloque android {}. También puedes agregar los parámetros de configuración a los tipos de compilación o a las variantes de producto para anular esos valores predeterminados para versiones diferentes de tu app.

En el siguiente archivo, se especifican los parámetros de configuración predeterminadas minSdk y targetSdk en el bloque defaultConfig {}, y se anula minSdk para una variante de producto.

android {
    ...
    defaultConfig {
        ...
        minSdk 21
        targetSdk 33
    }
    productFlavors {
        main {
            ...
        }
        afterNougat {
            ...
            minSdk 24
        }
    }
}

android {
    ...
    defaultConfig {
        ...
        minSdk = 21
        targetSdk = 33
    }
    productFlavors {
        create("main") {
            ...
        }
        create("afterNougat") {
            ...
            minSdk = 24
        }
    }
}

Cuando se prepara para instalar tu app, el sistema verifica el valor de esas configuraciones y las compara con la versión del sistema. Si el valor de minSdk es superior al de la versión del sistema, este evita que se instale la app.

Si no especificas estos parámetros de configuración, el sistema determinará que tu app es compatible con todas las versiones de la plataforma. Esto equivale a configurar minSdk en 1.

Para obtener más información, consulta ¿Qué es el nivel de API? Para ver los parámetros de configuración de compilación de Gradle, consulta Cómo configurar variantes de compilación.