KappS Base de conocimiento · Preguntas frecuentes

Gestión del código de versión y compatibilidad de actualizaciones en Google Play

Preguntas frecuentes Revisión de la app y publicación

1. Dos campos, dos funciones completamente distintas. La guía de versiones de Google los define por separado: versionCode es «un entero positivo que se usa como número de versión interno. Este número ayuda a determinar si una versión es más reciente que otra, y los números más altos indican versiones más recientes. No es el número de versión que se muestra a los usuarios; ese número lo define el ajuste versionName. El sistema Android usa el valor de versionCode para protegerse frente a degradaciones, ya que impide que los usuarios instalen un APK con un versionCode inferior al de la versión instalada en su dispositivo». versionName es «una cadena que se usa como número de versión mostrado a los usuarios... versionName es el único valor que se muestra a los usuarios». La ayuda de Play Console añade el detalle operativo con el que tropiezan primero los desarrolladores: versionCode es «un entero de 32 bits que aumenta de forma constante con cada nueva versión», mientras que versionName es «una cadena que representa el número de versión de cara al usuario, por ejemplo, "1.0.0", "1.1 Beta", "2.0"». Marketing puede renombrar 4.9 a 5.0 sin problema; en el momento en que el entero no aumenta, la subida falla. (§https://developer.android.com/studio/publish/versioning / §https://support.google.com/googleplay/android-developer/answer/17367361)

2. El filtro de subida de Play es una sola comparación, y es estrictamente mayor que. La lista oficial de requisitos de actualización fija tres condiciones obligatorias, en este orden: «El nombre del paquete del Android App Bundle actualizado debe ser el mismo que el de la versión actual. El código de versión debe ser mayor que el de la versión actual... El paquete de la app actualizado debe estar firmado con la misma firma que la versión actual». No existe una vía de «igual vale si el binario es distinto», ni hay argumento que valga en la revisión: la comprobación es mecánica y ocurre antes de que un humano o un bot de políticas llegue a ver la versión. (§https://support.google.com/googleplay/android-developer/answer/9859350)

3. Un versionCode nunca se puede reutilizar, y el conjunto pertenece a la app, no al canal. La guía de versiones es tajante: "No puedes subir un APK a Play Store con un versionCode que ya hayas usado para una versión anterior". En la consola eso aparece como el rechazo habitual "El código de versión X ya se ha utilizado". Como el contador está vinculado a la aplicación (el nombre del paquete), las pruebas internas, las pruebas cerradas, las pruebas abiertas y producción toman todos de la misma secuencia; para poner la misma compilación en un segundo canal, la añades "desde la biblioteca" en lugar de volver a subirla. Un nombre de paquete distinto —una app de staging, una variante de marca blanca con su propio applicationId— tiene su propia secuencia, y por eso precisamente una app de staging es el lugar adecuado para gastar códigos mientras depuras. (§https://developer.android.com/studio/publish/versioning)

4. El límite es 2.100.000.000, y alcanzarlo no es un ticket de soporte, es un estado final. Ambos documentos indican la misma cifra: "El valor máximo que Google Play permite para versionCode es 2100000000". La página de la consola detalla la consecuencia: "Si el versionCode de tu app alcanza o supera el límite máximo, ya no podrás subir nuevos APK ni paquetes de app a Google Play para esa aplicación. Esto significa que no habrá más correcciones de errores, nuevas funciones ni actualizaciones de compatibilidad para tus usuarios". El único remedio que indica Google es que "Google Play podría ofrecer soporte": un quizá, no un botón de reinicio. Para un negocio que gana con apps activas, la cifra es por tanto un activo con fecha de caducidad, y hay que gastarlo como tal. (§https://support.google.com/googleplay/android-developer/answer/17367361)

5. Tres hábitos de numeración agotan el rango más rápido de lo que los desarrolladores esperan. Las marcas de tiempo Unix en segundos ya superan los 1.790 millones y suben en cada compilación; un contador global de ejecuciones de CI compartido entre ramas, variantes y apps hermanas avanza a toda velocidad con cada pipeline fallido; y "número de compilación = número de commits" se dispara en el momento en que se reescribe el historial de un monorepo. La propia lista de mitigaciones de Play es: "Adoptar una estrategia sostenible de versionCode: implementar una estrategia de generación de versionCode que garantice un aumento gradual y constante y evite el consumo rápido del rango disponible. Supervisar el uso del versionCode: hacer un seguimiento periódico de la progresión del versionCode de tu app para anticipar cuándo puede acercarse al límite. Implementar comprobaciones automatizadas: integrar comprobaciones en los procesos de compilación y publicación para advertir o impedir el uso de valores de versionCode excesivamente altos". (§https://support.google.com/googleplay/android-developer/answer/17367361)

6. Los códigos se consumen al subir, no al publicar. Subir a pruebas internas, dejar un paquete en la biblioteca o crear una versión en borrador que luego se descarta dejan el número gastado: "Añadir desde la biblioteca" existe precisamente porque el mismo binario puede volver a asociarse a una versión posterior, pero nunca volver a crearse. Quien "sube una compilación a la consola para ver si pasa" paga un número de versión por intento; en una app de larga vida con un pipeline rápido, así es como un margen cómodo se convierte en una crisis años después.

7. Detener no es revertir, porque Android rechaza las versiones anteriores. La regla a nivel de sistema citada en el punto 1 (un dispositivo no instalará un versionCode inferior al ya instalado) es la razón por la que no hay ningún botón en la consola que devuelva a los usuarios a la compilación de la semana pasada. La guía de implementación por fases de Google dice lo mismo en términos operativos: "Si detectas un problema en tu paquete de la app actual, crea y publica una nueva versión con un paquete de la app corregido". Así que la única recuperación real frente a una compilación de producción defectuosa es un paquete nuevo, con un versionCode superior al defectuoso, publicado tan rápido como permita la revisión, y precisamente por eso el hueco de emergencia en tu esquema de numeración tiene que existir antes de que lo necesites. (§https://support.google.com/googleplay/android-developer/answer/6346149)

8. La implementación por fases es una herramienta exclusiva para actualizaciones y nunca avanza por sí sola. «Puedes publicar una actualización de la app en producción y en los canales de prueba mediante una implementación por fases. Con una implementación por fases, tu actualización llega solo a un porcentaje de tus usuarios, que puedes aumentar con el tiempo. Las implementaciones por fases solo pueden usarse para actualizaciones de la app, no al publicar una app por primera vez.» Y la trampa que deja las versiones atascadas al 5 % durante una semana: «el porcentaje de implementación por fases de tu app no aumentará automáticamente». Quien gestiona la publicación tiene que volver y subir el porcentaje; nada por parte de Google lo hará. Además, no se avisa a los usuarios de que recibieron una actualización por fases: «No se notificará a los usuarios si reciben una versión de tu app en una implementación por fases», así que los comentarios sobre una versión por fases deben extraerse de los datos de estado y del soporte, no de las reseñas. (§https://support.google.com/googleplay/android-developer/answer/6346149)

9. Qué cambia realmente detener una implementación por fases. «Si detectas un problema, puedes detener una implementación por fases para ayudar a minimizar el número de usuarios que experimentan el problema con tu app. Cuando detienes una implementación por fases, ningún usuario adicional recibirá la versión de la app de tu implementación por fases existente. Los usuarios que ya recibieron la versión de la app en tu versión de implementación por fases permanecerán en esa versión». De ahí se derivan dos consecuencias que muchos pasan por alto: reanudar no reordena la audiencia —«Cuando detienes y luego reanudas la implementación de tu versión, afectarás al mismo conjunto de usuarios»— y comenzar una nueva versión antes de que termine la anterior reutiliza esa misma cohorte: «Cuando haces una implementación por fases de una nueva versión antes de completar la implementación de la versión anterior, la nueva versión usará el mismo grupo de usuarios que la versión anterior (según el porcentaje de la implementación)». Tu corrección la valida el mismo 5 % desafortunado, no una muestra nueva. (§https://support.google.com/googleplay/android-developer/answer/6346149)

10. Detener una versión totalmente implementada: qué hace y qué no hace. «Si detectas un problema crítico en tu app, la función de detener la implementación minimiza las molestias para los usuarios al impedir que usuarios nuevos y existentes instalen o actualicen a la versión afectada de tu app. Cuando detienes una versión completa, la versión anterior de tu app volverá a estar disponible para los usuarios nuevos y para cualquiera que no esté usando la versión detenida de tu app». Se trata de un cambio de entrega, no de una desinstalación: «La versión detenida dejará de entregarse a los usuarios», pero los dispositivos que ya la recibieron la conservan, de nuevo por la protección contra degradaciones. En la misma página se indican tres límites: funciona «en cualquier canal, excepto los canales de pruebas internas»; «No puedes detener tu primera versión en un canal»; y «Si tu versión anterior tiene una infracción de políticas, no se puede usar en lugar de tu versión detenida». Una reanudación posterior puede ir a cualquier porcentaje, que es la forma correcta de reintroducir gradualmente una compilación corregida. (§https://support.google.com/googleplay/android-developer/answer/16285429)

11. Una versión pendiente por canal, y esto es lo que bloquea un hotfix en el peor momento. "No puedes crear una versión nueva mientras tengas versiones pendientes. Implementa al 100 % las versiones por fases o elimina los cambios en la página Resumen de publicación y descarta antes las versiones no publicadas". Una implementación por fases abandonada al 20 %, un envío a revisión a medio terminar o una retención de publicación gestionada que se queda en el canal de producción se interpondrán entre tú y la compilación de emergencia. El hábito que lo evita: después de cada versión, cierra el ciclo —implementa al 100 % o elimina y descarta— y anota el estado en el registro de versiones para que la siguiente persona (o tu yo del futuro) no tenga que depurar una consola que se niega a abrir una versión nueva. (§https://support.google.com/googleplay/android-developer/answer/9859348)

12. Un esquema de numeración que aguante diez años de versiones. Reserva bandas de ancho fijo para que la aritmética siga siendo legible y el techo quede muy lejos: versionCode = major * 100000 + minor * 1000 + patch * 10 + hotfix, lo que permite versiones mayores de la 1 a la 20999, mil versiones menores y diez espacios de patch/hotfix para cada una. Mantén el rango de trabajo visiblemente por debajo de los 2.100 millones en tu script de compilación y haz que la compilación falle (no la subida) cuando el valor calculado cruce un umbral flexible que fijes, por ejemplo, en 1.500 millones. Da a CI la potestad de incrementar solo al subir, nunca en cada commit; ejecuta cada compilación exploratoria bajo el applicationId de staging para que sus códigos se gasten en una secuencia distinta; y registra el versionCode publicado en las notas de la versión para que el número sea auditable y no conocimiento tribal.

13. Lista de verificación previa a la carga que detecta todo lo anterior en una sola pasada: (a) el versionCode es estrictamente mayor que cualquier código cargado alguna vez para esta app, en todos los canales, no solo en el que vas a usar; (b) versionName es solo texto visible y puede repetirse o saltar libremente; (c) el nombre del paquete no cambia y el paquete está firmado con la clave de firma activa; cambiar la clave de firma de la app significa que "los usuarios de los canales interno y cerrado que ya instalaron tu app dejarán de recibir actualizaciones. Esos usuarios deben desinstalar y reinstalar la app para recibir actualizaciones"; (d) la ruta de actualización se prueba en un dispositivo que ya tiene instalada la versión anterior, porque una instalación limpia no demuestra nada sobre una actualización; (e) el número se compara con el límite de 2.100.000.000 y con tu propio umbral interno; (f) no queda ninguna otra versión pendiente en el canal objetivo; y (g) aún hay un hueco de código de emergencia libre en la banda actual. Cada uno de estos puntos es un campo o un estado, no una decisión subjetiva, y por eso toda la lista puede vivir en CI y en la lista de verificación de versiones en lugar de en la memoria de alguien. (§https://support.google.com/googleplay/android-developer/answer/9859348)