Compatibilidad nativa

Una actualización en vivo de Capgo reemplaza el paquete JavaScript de tu aplicación instantáneamente, pero no puede cambiar la parte nativa de tu aplicación — los plugins de Cordova/__CAPGO_KEEP_0__, las dependencias nativas y la configuración del proyecto nativo que se compilan en el binario instalado. Cuando un nuevo paquete espera __CAPGO_KEEP_1__ nativos que el binario instalado no tiene, el paquete es incompatible con el sistema nativo incompatible con el sistema nativo part of your app — the Capacitor/Cordova plugins, native dependencies, and native project configuration that are compiled into the installed binary. When a new bundle expects native code that the installed binary doesn’t have, the bundle is incompatible con el sistema nativo: Capgo puede seguir entregándolo, pero puede que se caiga o se comporte mal en dispositivos que todavía están ejecutando la versión nativa más antigua.

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

Nota

Las actualizaciones en vivo están limitadas a cambios en el paquete de JavaScript. Si necesitas actualizar nativamente code — agregando o eliminando un plugin, actualizando Capacitor, o cambiando la configuración del proyecto nativo — necesitarás enviar un nuevo build binario a través del proceso de distribución habitual de la tienda de aplicaciones.

TLDR: OTA o nativo?

Capgo puede enviar archivos desde el carpeta de generación de la build web. Si el cambio solo afecta HTML, CSS, JavaScript, activos o paquetes de JavaScript puros empaquetados en ese resultado, envíalo como una actualización en vivo.

Utiliza una versión de aplicación nativa cuando un cambio actualiza capacitor.config.ts, la configuración del plugin almacenada en Capacitor config, plugins o dependencias nativos, Capacitor mismo o archivos de proyecto iOS/Android. Una comprobación práctica: si el cambio debe actualizar el proyecto nativo a través de npx cap sync o npx cap copy antes de que los dispositivos instalados puedan utilizarlo, tratalo como nativo.

Cambiar	¿Enviar con Capgo OTA?	¿Por qué
HTML, CSS, JavaScript de la aplicación, imágenes, fuentes y otros activos de construcción web	Sí	Se cargan desde el paquete de la web en tiempo de ejecución.
Cambios en paquetes de JavaScript puro integrados en su salida de web	Sí	El JavaScript generado forma parte del paquete de la web.
capacitor.config.ts Cambios	No	Capacitor config se lee en la aplicación nativa en tiempo de compilación.
Agregar, eliminar o actualizar Capacitor/plugins de Cordova	No	El binario nativo instalado debe contener el code nativo correspondiente.
Cambios en archivos de proyecto iOS o Android	No	Los usuarios existentes necesitan un nuevo binario desde las tiendas.

Plugins de cliente por pila

Capgo envía actualizadores de cliente dedicados para cada runtime híbrido:

Plugin	Usar cuando
@capgo/capacitor-updater	Capacitor aplicaciones iOS/Android
@capgo/cordova-updater	Aplicaciones de iOS 7+ / Android 13+ con Cordova
@capgo/electron-updater	Aplicaciones de escritorio de Electron

Los controles de compatibilidad nativa se aplican sin importar el plugin del cliente — comparan las dependencias nativas registradas del paquete con el binario instalado.

Por qué la compatibilidad nativa importa

Cada aplicación Capacitor se envía en dos capas:

• El binario nativo que los usuarios instalan desde la Tienda de App / Tienda de Juegos. Contiene Capacitor, tus plugins nativos y configuración nativa.
• El paquete de JavaScript (tu aplicación web) que Capgo puede actualizar por aire.

A la actualización en vivo solo intercambia la capa de JavaScript. Si ese nuevo JavaScript llama a un plugin nativo o API que no se ha compilado en el binario instalado, la llamada falla en tiempo de ejecución — lo que puede hacer que la aplicación se caiga o quebrar silenciosamente una característica. En pocas palabras: Capgo no puede actualizar los plugins nativos code, por lo que un dispositivo que ejecuta la versión nativa antigua no puede ejecutar de manera segura un paquete que se construyó contra nuevos plugins nativos code.

Cómo Capgo detecta la compatibilidad

Cuando subas un paquete — o ejecutes la comprobación manualmente — Capgo compara los paquetes nativos in your local project (your Capacitor/Cordova plugins and their versions) against the native packages recorded for the bundle actualmente en vivo en el canal:

• Si coinciden, la modificación es solo de JavaScript y segura para enviar por aire.
• Si se agregó, eliminó o cambió la versión de un plugin, el paquete es incompatible con el plugin nativo — esos cambios solo tienen efecto una vez que los usuarios instalen un nuevo binario nativo.

Ver desde el CLI

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

El CLI imprime una tabla de cada paquete nativo con su versión local, la versión en vivo en el canal 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

Agregar --text para intercambiar los emojis por OK/FAIL (útil en los registros de CI), y --package-json / --node-modules para apuntar a los caminos correctos en un monorepo.

Obtenga un veredicto legible por máquinas (CI)

Para las pipelines, bundle releaseType colapsa la verificació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

Bloquee su pipeline de liberación en esto: envíe un actualización en vivo cuando lo imprima OTAy active una compilación nativa cuando lo imprima native.

¿Qué significa una actualización incompatible para sus usuarios?

Cuidado

Por defecto, detectar incompatibilidad no bloquea la subida — si subes un paquete incompatibilidad nativa y lo estableces como la construcción activa de un canal, __CAPGO_KEEP_0__ no bloquea la subida — si subes un paquete incompatibilidad nativa y lo estableces como la construcción activa de un canal, Capgo entonces lo entregará a los dispositivos en ese canal. (Puedes convertir esto en una puerta dura con --fail-on-incompatible — ver Prevenir entregas incompatibles en

los dispositivos que aún están ejecutando la versión nativa anterior ,la falta de nativa code puede causar errores o características rotas — incluso aunque la actualización se descargó y se aplicó “con éxito.” Esto es por qué una actualización en vivo puede ser en vivo y entregada y aún así romper la aplicación para los usuarios existentes, y por qué Capgo puede advertirte cuando un paquete incompatibilidad va en vivo.

Capgo' rollback automático puede capturar un error de JavaScript lanzado antes notifyAppReady() runs, but it isn’t a substitute for shipping compatible native code — a mismatch that crashes later, or crashes natively, can slip past it.

Cómo enviar cambios nativos de manera segura

Publicar una nueva versión nativa (la solución real)

Cuando un paquete necesita una nueva versión nativa code, construya y envíe una nueva versión binaria a la Tienda de Aplicaciones / Tienda de Juegos (o reconstruya con Capgo Cloud Build). Una vez que los usuarios actualicen la versión binaria, las dependencias nativas del paquete se alinean y la actualización en vivo se ejecuta correctamente

Revertir si un paquete incompatible ya está en vivo

Si un paquete incompatible ya está activo en un canal, reemplace el canal con la última versión compatible para detener su servicio hasta que la versión nativa esté disponible. Consulte Revertir.

Prevenir envíos incompatibles

Dos guardianes complementarios, ambos de los cuales inspeccionan realmente tus paquetes nativos:

Fallar la carga en CI — --fail-on-incompatible

Agregar la bandera a tu bundle upload paso. Si los paquetes nativos del paquete no coinciden con la versión actualmente en vivo del canal, la carga falla con un código de salida no cero y nada se envía — por lo que tu pipeline te impide publicar silenciosamente una actualización OTA que no puede tener efecto hasta que los usuarios instalen una construcción nativa:

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

Envíos compatibles — y casos en los que la comprobación no puede ejecutarse (un nuevo canal, o no hay metadatos remotos) — pasan sin cambios. En una terminal interactiva ofrece en su lugar el flujo de construcción nativa del Constructor Capgo; rechazar falla. (No se puede combinar con --ignore-metadata-check.)

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

When you hagas envíe la compilación nativa y el paquete juntos, coloque el canal en la metadata estrategia y suba con --auto-min-update-version. Capgo realiza la comprobación de compatibilidad en cada subida y, cuando un paquete necesita nuevos componentes nativos code, eleva el piso de actualización para que los dispositivos que no han instalado la compilación nativa 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

Las reglas de número de versión como --disable-auto-update major no son un sustituto — solo bloquean los saltos de versión y nunca inspeccionan el código nativo code, por lo que un cambio nativo enviado en una versión menor o de parche todavía se envía. Utilice --fail-on-incompatible o --auto-min-update-version, que revisan sus paquetes nativos.

Consulte Versión de destino para obtener la completa lista de opciones de destino.

Relacionado

Versión de destino

Entrega solo paquetes compatibles utilizando canales, reglas de semver y la estrategia de metadatos.

Reversiones

Revertir un canal a la última construcción compatible si un paquete incompatible salió en vivo.

Tipos de Actualización

Cómo aplicar condiciones de tiempo, retraso y bloqueo de versión funcionan juntos.

CLI: paquete

Referencia para la compatibilidad del paquete, releaseType y opciones de carga.

Sigue adelante desde la compatibilidad nativa

Si estás utilizando Compatibilidad nativa para mantener actualizaciones en vivo seguras, conecta con Bloqueo de Versión para enviar paquetes por versión nativa, Rollbacks para recuperar cuando un paquete incompatible se envía, Tipos de actualización para entender la versión bloqueante del canal, y el Capgo CLI referencia del paquete para los comandos de compatibilidad y releaseType.