Compatibilidad nativa

Un Capgo live update reemplaza el Bundle de JavaScript al instante, pero no puede cambiar la parte nativa de tu app: los plugins de Capacitor/Cordova, las dependencias nativas y la configuración del proyecto nativo que se compilan en el binario instalado. Si un nuevo bundle requiere code nativo que el binario instalado no tiene, el bundle se incompatible con nativo: Capgo aún puede entregarlo, pero podría fallar o comportarse mal en dispositivos que siguen ejecutando el build nativo anterior.

Esta página explica cómo Capgo detecta la compatibilidad nativa, qué significa una actualización incompatible para tus usuarios y cómo publicar cambios nativos de forma segura.

Nota

Los Live Updates se limitan a cambios en el bundle de JavaScript. Si necesitas actualizar el code nativo —añadir o eliminar un plugin, actualizar Capacitor o cambiar la configuración del proyecto nativo— tendrás que enviar un nuevo build binario mediante el proceso habitual de distribución en las tiendas.

TLDR: ¿OTA o nativo?

Capgo puede enviar archivos desde tu carpeta de build web generada. Si el cambio solo afecta a HTML, CSS, JavaScript, assets o paquetes de JavaScript puro incluidos en ese output, publícalo como un live update.

Usa un release nativo de la app cuando un cambio actualice capacitor.config.ts, la configuración de plugins guardada en la config de Capacitor, plugins o dependencias nativas, el propio Capacitor o archivos de proyecto de iOS/Android. Una comprobación práctica: si el cambio debe actualizar el proyecto nativo mediante npx cap sync o npx cap copy antes de que los dispositivos instalados puedan usarlo, trátalo como nativo.

Cambio	¿Publicar con Capgo OTA?	Por qué
HTML, CSS, JS de la app, imágenes, fuentes y otros assets del build web	Sí	Se cargan desde el web bundle en tiempo de ejecución.
Cambios en paquetes de JavaScript puro incluidos en tu output web	Sí	El JavaScript generado forma parte del bundle web.
capacitor.config.ts cambios	No	La configuración de Capacitor se lee en la app nativa al hacer el build.
Añadir, eliminar o actualizar plugins de Capacitor/Cordova	No	El binario nativo instalado debe contener el code nativo correspondiente.
Cambios en archivos de proyecto iOS o Android	No	Los usuarios actuales necesitan un nuevo binario de las tiendas.

Plugins de cliente por stack

Capgo incluye clientes de actualización dedicados para cada runtime híbrido:

Plugin	Cuándo usar
@capgo/capacitor-updater	Apps iOS/Android de Capacitor
@capgo/cordova-updater	Apps Cordova iOS 7+ / Android 13+
@capgo/electron-updater	Apps de escritorio Electron

Las comprobaciones de compatibilidad nativa se aplican independientemente del plugin del cliente: comparan las dependencias nativas registradas en el bundle con el binario instalado.

Por qué importa la compatibilidad nativa

Cada app de Capacitor se distribuye en dos capas:

• El binario nativo los usuarios la instalan desde la App Store / Play Store. Contiene Capacitor, tus plugins nativos y la configuración nativa.
• El Bundle de JavaScript (tu web app) que Capgo puede actualizar over the air.

Un live update solo reemplaza la capa de JavaScript. Si ese nuevo JavaScript llama a un plugin nativo o a un API que no está compilado en el binario instalado, la llamada falla en tiempo de ejecución, lo que puede hacer que la app se cierre o que una función se rompa silenciosamente. En pocas palabras: Capgo no puede actualizar el code nativo, por lo que un dispositivo con el build nativo antiguo no puede ejecutar de forma segura un bundle construido contra nuevos code nativos.

Cómo Capgo detecta la compatibilidad

Cuando subes un bundle — o ejecutas la comprobación manualmente —, Capgo compara los paquetes nativos de tu proyecto local (tus plugins de Capacitor/Cordova y sus versiones) con los paquetes nativos registrados para el bundle actualmente activo en el canal:

• Si coinciden, el cambio es solo de JavaScript y es seguro publicarlo over the air.
• Si se añadió, eliminó o cambió de versión un plugin, el bundle es incompatible con nativo — esos cambios solo surten efecto cuando los usuarios instalan un nuevo binario nativo.

Compruébalo desde CLI

bunx @capgo/cli@latest bundle compatibility com.example.app --channel production

El CLI muestra una tabla de cada paquete nativo con su versión local, la versión activa en el channel y un estado:

Package              Local    Remote   Status
@capacitor/core      6.1.2    6.1.2    ✅
@capacitor/share     6.0.0    6.0.0    ✅
@capacitor/camera    6.1.0    —        ❌  not in the live bundle

Consejo

Añadir --text para cambiar los emojis por OK/FAIL (útil en los logs de CI), y --package-json / --node-modules apuntar a las rutas correctas en un monorepo.

Obtener un veredicto legible por máquina (CI)

Para pipelines, bundle releaseType resume la comprobación en una sola palabra:

bunx @capgo/cli@latest bundle releaseType com.example.app --channel production
# → OTA      safe to ship as a live update
# → native   needs a new app-store build

Condiciona tu pipeline de release a esto: lanza un live update cuando imprima OTA, y dispara un Native Build cuando imprima native.

Qué significa una actualización incompatible para tus usuarios

Precaución

Por defecto, detectar una incompatibilidad no necesitas bloquea la subida — si subes un bundle incompatible con la versión nativa y lo estableces como build activo de un canal, Capgo lo entregará a los dispositivos de ese canal. (Puedes convertir esto en un bloqueo estricto con --fail-on-incompatible — consulta Evitar entregas incompatibles abajo.)

En dispositivos que aún ejecutan el binario nativo anterior, la falta del code nativo puede causar crashes o fallos en las funciones — aunque la actualización se haya descargado y aplicado con “éxito”. Por esto, un live update puede estar activo y entregado pero aun así romper la app para los usuarios actuales, y por eso Capgo puede avisarte cuando un bundle incompatible se publica.

de Capgo rollback automático puede capturar un error de JavaScript lanzado antes notifyAppReady() de ejecutarse, pero no sustituye a la publicación de un code nativo compatible: una incompatibilidad que provoque un crash posterior o nativo puede pasar desapercibida.

Cómo lanzar cambios nativos de forma segura

Publicar un nuevo Native Build (la solución real)

Cuando un bundle requiere un nuevo code nativo, compila y envía un nuevo binario a la App Store / Play Store (o recompila con Capgo Cloud Build). Una vez que los usuarios actualicen el binario, las dependencias nativas del bundle coincidirán y el live update se ejecutará correctamente.

Hacer rollback si un bundle incompatible ya está live

Si un bundle incompatible ya está activo en un canal, revierte el canal a la última build compatible para dejar de servirlo hasta que salga la build nativa. Ver Reversiones.

Evitar entregas incompatibles

Dos protecciones complementarias que inspeccionan tus paquetes nativos:

Haz fallar el upload en CI — --fail-on-incompatible

Añade el flag a tu bundle upload paso. Si los paquetes nativos del bundle no coinciden con la versión activa del canal, la subida falla con un exit code distinto de cero y no se publica nada — así tu pipeline evita que publiques silenciosamente un update OTA que no surtirá efecto hasta que los usuarios instalen un build nativo:

bunx @capgo/cli@latest bundle upload --channel production --fail-on-incompatible

Los uploads compatibles —y los casos en los que el check no puede ejecutarse (un canal nuevo o sin metadatos remotos)— pasan sin cambios. En una terminal interactiva, en su lugar ofrece el flujo de native build de Capgo Builder; si se rechaza, falla. (No se puede combinar con --ignore-metadata-check.)

Consejo

Cuando intencionadamente necesites un bundle que difiera de los paquetes nativos en vivo del canal (nuevo plugin, actualización de Capacitor, etc.), omite --fail-on-incompatible para esa carga de baseline. Mantén la flag en el CI de OTA diario. Flujo completo del canal: Workflow de canales Native + OTA.

Controla la entrega por versión nativa — metadata + --auto-min-update-version

Cuando no publica el build nativo y el bundle juntos, pon el canal en el metadata estrategia y sube con --auto-min-update-version. Capgo ejecuta la comprobación de compatibilidad en cada upload y, cuando un bundle necesita nuevos code nativos, eleva el umbral mínimo de actualización para que los dispositivos que no hayan instalado el Native Build correspondiente no lo reciban:

# one-time: switch the channel to the metadata strategy
bunx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadata

# from then on, Capgo sets the floor automatically on every upload
bunx @capgo/cli@latest bundle upload --channel production --auto-min-update-version

Precaución

Reglas de número de versión como --disable-auto-update major son necesitas un sustituto: solo bloquean los saltos de versión y nunca inspeccionan el code nativo, así que un cambio nativo incluido en un release minor o patch se distribuye igual. Usa --fail-on-incompatible o --auto-min-update-version, que comprueban tus paquetes nativos.

Ver Segmentación por versión para el conjunto completo de opciones de targeting.

Relacionado

Workflow nativo + OTA

Canales dev/producción, cuándo mantener --fail-on-incompatible, y cómo publicar una línea base nativa intencional.

OTA automático o nativo

Conecta bundle releaseType en GitHub Actions o GitLab para que CI elija live update vs Capgo Build.

Segmentación por versión

Entrega solo bundles compatibles usando canales, reglas semver y la estrategia de metadatos.

Reversiones

Revierte un canal a la última build compatible si un bundle incompatible se publicó.

Tipos de actualización

Cómo funcionan juntos el timing de aplicación, las condiciones de retraso y el bloqueo de versiones.

CLI: bundle

Referencia para la compatibilidad de bundles, releaseType y opciones de upload.

Continuar desde Compatibilidad nativa

Si estás usando Compatibilidad nativa to keep live updates safe, connect it with Segmentación por versión para enrutar bundles por versión nativa, Reversiones para recuperarse si se despliega un bundle incompatible, Tipos de actualización para entender el bloqueo de versiones por canal, y la Capgo CLI referencia de bundle para los comandos compatibility y releaseType.