Capgo version_build vs version_name: Pasos de configuración

Capgo’s version names can feel backward at first: version_build es el baseline de la app nativa, mientras que version_name registra el bundle en el dispositivo. Si entiendes bien la diferencia, puedes verificar por qué un dispositivo recibirá o no una actualización OTA antes de desplegarla.

Analizamos las páginas de solución de problemas de 5 plataformas de live-update, incluida la nuestra, y descubrimos que nuestra documentación lista 7 códigos de desajuste de version_build con nombre, frente a 5, 2, 2 y 0 de las otras cuatro. Más códigos con nombre significa menos conjeturas cuando aparece un desajuste de version_build.

Tabla de contenidos

• Paso 1: Localiza version_build y version_name en Capgo
• Paso 2: Identifica el baseline nativo y el bundle descargado
• Paso 3: Comprueba el origen de la versión de tu app nativa
• Paso 4: Configura y verifica la versión del bundle que recibe Capgo
• Paso 5: Prueba la elegibilidad del canal antes de desplegar una actualización
• Paso 6: Diagnosticar desajustes de versión y lograr releases repetibles
• FAQ
• Conclusión

Paso 1: Localiza version_build y version_name en Capgo

Empieza tratando estos datos como dos hechos distintos de una misma instalación. version_build le indica a Capgo qué versión de la app nativa hay en el dispositivo. version_name le indica a Capgo qué bundle de JavaScript ha descargado el dispositivo. Pueden tener valores distintos, y eso es lo normal.

En el modelo de versiones de Capgo, la versión nativa es el punto de referencia para la elegibilidad de actualizaciones. Capgo compara el bundle asignado a un canal con esa línea base nativa. La versión del bundle instalado en el dispositivo ayuda a identificar su code web actual, pero no reemplaza la línea base nativa en las reglas de versión del canal.

Busca el dispositivo en la página Dispositivos de la consola de Capgo y anota ambos valores antes de depurar. Luego, compáralos con el bundle objetivo del canal. El reglas de canal de Capgo explican cómo se verifica la versión objetivo de un canal contra version_build.

Mantén los tres valores en columnas separadas en una nota de release o un informe de pruebas. Si el equipo escribe una única “app version” genérica, es fácil comparar el par equivocado. Para la elegibilidad, compara el bundle de destino con version_build. Para el code web instalado, verifica version_name.

La nomenclatura de Capgo puede parecer ajena a las convenciones de Android, donde los equipos suelen usar “build” para un número de build incremental. Aquí, lee el campo por su rol Capgo, no por lo que sugiere el nombre. Ese pequeño hábito evita muchas confusiones en el release.

Paso 2: Identifica el baseline nativo y el bundle descargado

Antes de cambiar un valor de versión, identifica cuál code es nativo y cuál code se entrega como bundle. La app nativa es el binario instalado de iOS o Android. El bundle contiene los assets web que una app Capacitor puede recibir mediante una actualización OTA.

Imagina una app nativa publicada con una versión base 1.2.3. Un fix web posterior se sube como bundle 1.2.4. Capgo comprueba si el bundle objetivo del canal está permitido para el baseline nativo 1.2.3. Si es elegible, el dispositivo puede descargar ese bundle. Tras la instalación, version_name refleja el bundle que hay ahora en el dispositivo. El baseline nativo sigue vinculado al binario instalado.

Esa diferencia importa cuando un usuario tiene un build antiguo de la App Store pero un bundle web más nuevo. El bundle puede cambiar sin reemplazar el binario nativo, pero una actualización OTA no puede añadir code nativo que no estuviera en la app. Si un cambio requiere un nuevo plugin o ajuste nativo, planifica un Native Build en lugar de tratar una subida de bundle como sustituto.

Usa esta comprobación rápida cuando los valores parezcan desincronizados:

• Confirma qué binario nativo está instalado en el dispositivo de prueba.
• Localiza el valor de versión que Capgo recibe como baseline nativo.
• Comprueba la versión del bundle asignada al canal del dispositivo.
• Anota la versión del bundle instalado por separado de ambos.

No infieras el baseline nativo a partir de package.json a menos que tu proceso de build copie deliberadamente ese valor en la versión nativa o en la configuración de Capgo. La versión de un proyecto JavaScript y la de una app instalada desde la tienda pueden desincronizarse. La fuente correcta es la que tu app envía realmente a Capgo.

Una vez que puedas identificar el baseline y el bundle actual, la siguiente tarea es rastrear cada valor hasta su archivo de origen. Ahí es donde suelen aparecer las diferencias entre plataformas.

Paso 3: Comprueba el origen de la versión de tu app nativa

Para una comparación fiable version_build, busca la versión nativa que reporta tu app de Capacitor. La documentación de versiones de Capgo describe distintas claves de origen para iOS y Android y luego usa el valor nativo resultante como baseline para la comparación OTA.

En iOS

Verificar CFBundleShortVersionString en la app Info.plist. In most Xcode projects that key is set to $(MARKETING_VERSION), por lo que el valor que realmente editas es el Marketing Version del target. Verifica el valor en la app compilada, no solo en una plantilla o en un archivo que tu build pueda sobrescribir.

Cuando un equipo actualiza el proyecto de Xcode pero no el valor que llega a la app, la vista local del proyecto puede parecer correcta mientras el binario instalado reporta algo distinto. Compara la versión en la app nativa generada con el valor que espera tu proceso de release.

En Android

Verificar defaultConfig.versionName en la configuración de Gradle de la app para Android. Ese nombre de versión nativa se usa en la comparación OTA de Capgo. No lo confundas con un build de Android code o con una versión de paquete JavaScript no relacionada. Para esta comprobación, la pregunta clave es qué nombre de versión envía la app nativa.

Una política de versiones compartida puede ayudar a que ambas plataformas se mantengan alineadas, pero no asumas que ya comparten una misma fuente. iOS y Android pueden tener archivos, pasos de build o tiempos de lanzamiento separados. Compara sus valores finales durante la verificación de lanzamiento, especialmente si una plataforma tiene un calendario de despliegue en la tienda diferente.

Algunas apps establecen explícitamente la versión nativa en capacitor.config.ts a través del valor de versión en la configuración del updater. El Probador de Semver de Capgo describe esta línea base nativa como un valor que puede provenir de la configuración o de los metadatos de la app nativa. Si tu app sobrescribe los metadatos nativos, documenta esa decisión para que nadie espere que la versión de la tienda sea la fuente.

Para cada plataforma, anota el archivo de origen, el valor resuelto y el build que lo contiene. Esto facilita rastrear una discrepancia después de un release, cuando el repositorio ya puede contener una versión más nueva que la app instalada en el dispositivo de un tester.

Solo modifica el archivo de origen que tu build lee realmente. Editar un archivo obsoleto puede hacer que una revisión de code parezca completa, dejando la versión nativa empaquetada sin cambios.

Paso 4: Configura y verifica la versión del bundle que recibe Capgo

La versión del bundle describe la actualización de JavaScript, no el binario nativo instalado. Capgo puede obtener esa versión del version campo en package.json cuando no proporciones una versión de bundle explícita. La opción de CLI --bundle puede establecer la versión enviada durante el upload.

Elige un camino y déjalo claro en tu proceso de release. Si package.json es la fuente, incrementa ese campo antes de subir. Si CI pasa una versión de bundle a través de CLI, haz que el job imprima la versión resuelta en su log de release. Una mezcla silenciosa de ambos caminos dificulta saber por qué el canal recibió un valor específico.

Usa versionado semántico en el formato habitual major.minor.patch forma, como 1.2.3. Las estrategias de canal de Capgo usan las partes de esa versión para decidir si un bundle objetivo encaja con una línea base nativa. Un sufijo de pre-release como -beta.1 pueden ayudar a etiquetar builds específicos de canal, pero mantén la versión parseable y coherente en tus herramientas de release.

Piensa en el incremento antes de publicar:

• Usa un cambio de patch para una corrección web compatible dentro de la misma línea de release.
• Usa un cambio minor cuando el cambio pertenezca a una nueva línea de funcionalidades compatibles.
• Usa un cambio major cuando cambie el límite de compatibilidad y el code nativo antiguo pueda no soportar el bundle.

Esas etiquetas son una convención de equipo, no una forma de añadir capacidad nativa vía OTA. Un número de versión no puede garantizar que un bundle sea seguro para una app nativa. Mantén las decisiones reales de compatibilidad vinculadas al code y a las dependencias del binario.

Antes del upload, compara la versión del paquete o el valor de CLI con la versión que se muestra para el bundle tras el upload. Inspecciona también el channel que lo servirá. Hacer el upload de un bundle con el nombre correcto a un channel no deseado puede aun así dar un resultado de test incorrecto.

Los strings inválidos o inconsistentes merecen una pausa para verificar, no una suposición. Mantén un valor de release validado, corrige el origen y prueba la versión resuelta antes de promoverla.

El Referencia del comando Capgo CLI es útil cuando integras el upload en un script, ya que la versión del bundle es parte de los inputs del comando de release.

Paso 5: Prueba la elegibilidad del canal antes de desplegar una actualización

La elegibilidad del channel es una comparación, no una suposición basada en qué bundle parece más nuevo. Capgo comprueba el target bundle del channel contra la base nativa enviada como version_build. El bundle descargado actualmente, reportado como version_name, no es la base para esas reglas de channel.

Por ejemplo, supongamos que una app nativa instalada informa 1.2.3, mientras que su bundle actual es 1.2.4. Si un canal apunta a 1.2.5, evalúa el objetivo contra la línea base nativa 1.2.3, no solo contra el bundle actual 1.2.4. Qué objetivos están permitidos depende de la estrategia de actualización del canal.

Capgo documenta estrategias como major y minor que restringen las actualizaciones respecto a la línea base nativa. Con una estrategia major, se puede bloquear un objetivo con una versión major superior. Con una estrategia minor, se puede bloquear un objetivo que cambie la línea major o minor de la línea base. Revisa la estrategia configurada en lugar de asumir que se aceptará cualquier bundle que parezca más nuevo.

Prueba la combinación exacta que planeas lanzar:

1. Instala el build nativo que representa a los usuarios a los que te diriges.
2. Confirma la línea base nativa enviada a Capgo.
3. Asigna el dispositivo de prueba al canal previsto.
4. Verifica el target del canal y su estrategia de versiones.
5. Solicita una actualización y confirma el resultado del dispositivo.

Realiza la misma comprobación en otra baseline nativa si tu base de usuarios tiene más de una versión de la tienda en uso. Un bundle que funciona para un build nuevo puede estar bloqueado para un binario antiguo, y esa puede ser la regla de seguridad prevista.

Para lanzamientos más amplios, empieza con un canal de pruebas o un rollout limitado. Vigila los resultados de elegibilidad inesperados antes de ampliar la audiencia. El modelo de canales de Capgo permite a los equipos dirigir bundles a través de canales de release; mantén claros el target y la línea nativa prevista de cada canal en tus notas de lanzamiento.

Si un dispositivo de prueba no se actualiza, revisa su asignación de canal y los valores de versión antes de volver a subir. Publicar repetidamente el mismo bundle no solucionará un desajuste de baseline.

Paso 6: Diagnosticar desajustes de versión y lograr releases repetibles

Cuando los valores no coincidan con lo esperado, rastréalos en orden. Primero, confirma la versión de la app nativa en el dispositivo. Luego, comprueba si un override de configuración cambia la baseline. Después, compara la versión del bundle que recibió Capgo con el target del canal. Esta secuencia separa un valor de origen erróneo de una regla de canal que funciona según lo configurado.

Las causas comunes incluyen hacer bump de package.json mientras se mantiene la versión nativa sin cambios, se compila una plataforma desde una rama de release diferente y se prueba un dispositivo asignado a otro canal. Otra fuente de confusión es llamar a cada número «versión de build». Anota qué valor es nativo, cuál es el bundle subido y cuál está instalado actualmente.

Para CI/CD, haz explícitas las entradas de versión. Deja que el pipeline lea la versión de release prevista desde una fuente controlada y pásala al comando de upload o actualiza el campo del paquete antes del paso de upload. Registra la línea base nativa resuelta y el objetivo del bundle en la salida del job. Evita depender del estado local de un desarrollador que el servidor de build no puede ver.

Usa una puerta de release que falle si falta una versión requerida o tiene un formato que tu equipo no acepta. Luego, realiza un upload de prueba al canal correcto antes de la promoción. Capgo admite un flujo de despliegue basado en CLI, por lo que los equipos pueden incluir el upload del bundle en su job de CI/CD existente y conservar un registro de comandos visible.

No confundas estos valores con la versión del motor WebView de Android. Nuestro @capgo/capacitor-webview-version-checker plugin comprueba si el motor WebView de un dispositivo está desactualizado y puede mostrar un prompt de actualización nativa. Esa es una pregunta separada de version_build y version_name, por lo que nunca sustituye la verificación de la baseline nativa y el bundle objetivo del canal.

Al migrar desde un esquema legacy, no renombres todos los valores existentes de una sola vez. Primero mapea la versión nativa antigua al native baseline. Luego mapea el web release subido a la bundle version. Prueba builds representativas de la app existente contra la estrategia del channel antes de dirigir a los usuarios a él.

Mantén un registro breve del release con el commit de origen, la versión nativa, la bundle version subida, el channel y el resultado de la prueba. Si un release debe pausarse o revertirse, ese registro ayuda al equipo a identificar qué bundle llegó a dónde. También hace que el siguiente deployment sea repetible en lugar de depender de que alguien recuerde qué archivo se cambió.

FAQ

¿Cuál es la diferencia entre version_build y version_name en Capgo?

version_build es el baseline de la app nativa, mientras que version_name es la bundle version descargada actual. Capgo usa el native baseline cuando verifica la elegibilidad del target bundle de un channel. Mantén ambos valores separados en logs y release notes para saber qué app nativa está instalada y qué web bundle tiene.

¿version_name controla si se permite una actualización OTA?

No, las estrategias de versiones de channel de Capgo comparan el target bundle con version_build, el native baseline. version_name identifica la bundle version descargada actual. Si un dispositivo no recibe una actualización, revisa su baseline, el target del channel y la estrategia configurada antes de cambiar el valor actual del bundle.

¿De dónde obtiene Capgo la versión nativa?

En iOS, Capgo lee CFBundleShortVersionString, que Xcode suele rellenar a partir de MARKETING_VERSION. En Android, la versión nativa proviene de defaultConfig.versionName. Una versión de updater explícita en la configuración de Capacitor puede cambiar el valor que tu app envía, así que verifica la app compilada.

¿De dónde obtiene Capgo la versión del bundle?

Capgo puede usar el version campo en package.json cuando no se especifica una versión de bundle explícita. También puedes proporcionar la versión con los CLI --bundle opción. Elige una única fuente clara para tu flujo de release y verifica la versión Capgo recibida tras el upload.

Conclusión

Usa version_build para la línea base nativa y version_name para el bundle instalado. Antes de tu próximo despliegue, verifica ambos valores en un dispositivo de prueba y compara el objetivo del canal con la línea base. Esa única comprobación puede detectar una discrepancia de versión antes de que llegue a una audiencia más amplia.