Compatibilidad nativa

A Capgo live update replaces your app’s paquete de JavaScript instantáneamente, pero no puede cambiar el JavaScript 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 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 necesita actualizar code nativo — agregando o eliminando un plugin, actualizando Capacitor, o cambiando la configuración del proyecto nativo — deberá enviar un nuevo build binario a través del proceso de distribución de la tienda de aplicaciones habitual.

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íelo como un live update.

Use una versión de la aplicación nativa cuando un cambio actualice 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 usarlo, trátelo como nativo.

Cambiar	¿Envíar 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 empaquetados en tu salida web	Sí	El JavaScript generado forma parte del paquete de la web.
capacitor.config.ts Cambios	No	Capacitor configura 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 clientes dedicados para cada runtime híbrido:

Plugin	Usar cuando
@capgo/capacitor-updater	Capacitor aplicaciones iOS/Android
@capgo/cordova-updater	Cordova aplicaciones iOS 7+ / Android 13+
@capgo/electron-updater	aplicaciones de escritorio 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 Capacitor aplicación se envía en dos capas:

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

Un live update intercambia solo la capa de JavaScript. Si ese nuevo JavaScript llama a un plugin nativo o API que no está 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 code nativo, por lo que un dispositivo que ejecuta la versión nativa antigua no puede ejecutar seguramente una paquete que se construyó contra nuevas code nativas.

Cómo Capgo detecta la compatibilidad.

Cuando subas un paquete — o ejecutes la comprobación manualmente — Capgo compara los paquetes nativos en tu proyecto local (los plugins de Cordova de tu Capacitor y sus versiones) con los paquetes nativos registrados para el paquete actualmente disponible en el canal:

• Si coinciden, el cambio es solo JavaScript y seguro para enviar por aire.
• Si se agregó, eliminó o cambió la versión de un plugin, el paquete es native-incompatible – esas cambios solo tienen efecto una vez que los usuarios instalen una nueva binaria nativa.

Verifique 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 cambiar los emojis por OK/FAIL (útil en registros de CI), y --package-json / --node-modules punter 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 lanzamiento en esto: envíe un live update cuando imprima OTAy active una compilación nativa cuando imprima native.

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

Cuidado

Por defecto, detectar incompatibilidad no not bloquear la subida — si subes un paquete incompatibilidad nativa y lo estableces como la construcción activa de un canal, Capgo Lo entregará a dispositivos en ese canal. (Puedes convertir esto en una puerta dura con) --fail-on-incompatible — see Evite entregas incompatibles below.)

binario nativo más antiguo binario nativo más antiguo, the missing native code can cause crashes or broken features — even though the update downloaded and applied “successfully.” This is why a live update can be live and delivered yet still break the app for existing users, and why Capgo can warn you when an incompatible bundle goes live.

Capgo’s devolución automática puede capturar un error de JavaScript lanzado antes notifyAppReady() que se ejecuta, pero no es un sustituto para enviar cambios nativos compatibles con code — una incompatibilidad que provoca un error más tarde, o provoca un error nativo, puede pasar desapercibida.

Cómo enviar cambios nativos de manera segura

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

Cuando un paquete necesita nuevos cambios nativos de code, compile y envíe una nueva binaria a la Tienda de Aplicaciones / Tienda de Juegos (o reconstruya con Capgo Cloud Build). Una vez que los usuarios actualicen la binaria, las dependencias nativas del paquete se alinean y live update se ejecuta correctamente.

Revertir si un paquete incompatible ya está en vivo

Si un paquete incompatible ya está activo en un canal, reversione el canal a la última compilación compatible para detener su servicio hasta que se publique la compilación nativa. Consulte Reversiones.

Prevenir envíos incompatibles

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

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

Agregar la bandera a tu bundle upload Si los paquetes nativos del bundle no coinciden con la versión actualmente en vivo del canal, la subida Falla con un código de salida no cero y nada se envía — para que tu pipeline te impida publicar una actualización OTA en silencio que no puede tener efecto hasta que los usuarios instalen una compilación nativa:

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

Envíos compatibles — y casos en los que el cheque 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 Capgo Builder; declinar falla. (No se puede combinar con --ignore-metadata-check.)

Consejo

Cuando usted intencionalmente necesita un paquete que difiere de los paquetes nativos en vivo del canal (nuevo plugin, Capacitor actualización, y así sucesivamente), omita --fail-on-incompatible Mantenga la bandera en OTA CI diario. Flujo de trabajo de canal completo: Nativo + Canal de actualizaciones OTA.

Entrega por versión nativa — metadata + --auto-min-update-version

Cuando usted haga envíe el paquete nativo y el paquete juntos, coloque el canal en la metadata estrategia y suba con --auto-min-update-version. Capgo ejecuta la comprobación de compatibilidad en cada carga y, cuando un paquete necesita una nueva versión nativa code, eleva el piso de actualización para que los dispositivos que no han instalado la versión nativa correspondiente no la reciben:

# 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

Cuidado

Versión-número reglas como --disable-auto-update major no son no un sustituto — solo bloquean saltos de versión y nunca inspeccionan la versión nativa code, por lo que un cambio nativo enviado en una versión menor o de parche sigue saliendo. Use --fail-on-incompatible o --auto-min-update-version, que compruebe sus paquetes nativos.

See Versión de destino para obtener la completa serie de opciones de destino.

Relacionado

Flujo de trabajo nativo + OTA

Canales de desarrollo y producción, cuando mantener --fail-on-incompatible, y cómo enviar una base nativa intencional.

Auto OTA o Nativo

Hilo bundle releaseType en GitHub Acciones o GitLab para que CI capture live update vs Capgo Compilación.

Versión de destino

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

Rollbacks

Revertir un canal a la última versión compatible si un paquete incompatible se publicó.

Tipos de Actualizaciones

Cómo aplican el tiempo, las condiciones de retraso y el bloqueo de versión en conjunto.

CLI: paquete

Referencia para la compatibilidad de paquetes, tipo de lanzamiento y opciones de carga.

Sigue adelante desde la compatibilidad nativa

Si estás utilizando Compatibilidad Nativa para mantener las actualizaciones en vivo seguras, conecta con Objetivos de Versión para rutas de paquetes por versión nativa, Reversiones para recuperarse cuando un paquete incompatible se envía, Tipos de Actualizaciones para entender la versión del canal que bloquea y el Capgo CLI referencia del paquete para los comandos de compatibilidad y releaseType.