Compatibilidad nativa

Una actualización en vivo de Capgo reemplaza el paquete de JavaScript de su aplicación Configuración con IA de inmediato, pero no puede cambiar la 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 no compatible con el nativo: Capgo puede enviarlo todavía, pero puede que se caiga o se comporte mal en dispositivos que todavía están ejecutando la construcció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 code nativa — agregando o eliminando un plugin, actualizando Capacitor, o cambiando la configuración de proyecto nativa — debes enviar un nuevo paquete de construcción binaria a través del proceso de distribución de tiendas de aplicaciones habitual.

TLDR: OTA o nativo?

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

Use a native app release when a change updates capacitor.config.tsLa configuración del plugin se almacena en Capacitor config, plugins nativos o dependencias, Capacitor mismo, o archivos de proyecto iOS/Android. npx cap sync Una comprobación práctica: si el cambio debe actualizar el proyecto nativo a través de npx cap copy o

antes de que los dispositivos instalados puedan utilizarlo, trátelo como nativo.	Ship with Capgo OTA?	¿Enviar con __CAPGO_KEEP_0__ 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 Pure-JavaScript empaquetados en su salida web	The JavaScript generado es parte del paquete web.
capacitor.config.ts Cambios	No	Capacitor no 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 archivo 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	Aplicaciones iOS 7+ / Android 13+ de Cordova
@capgo/electron-updater	Aplicaciones de escritorio de Electron

Se aplican comprobaciones de compatibilidad nativa independientemente del 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 Los usuarios instalan desde la Tienda de Aplicaciones / Tienda de Juegos. Contiene Capacitor, sus plugins nativos, y la configuración nativa.
• El paquete de JavaScript (su aplicación web) que Capgo puede actualizar por aire.

Una actualización en vivo 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 rompa silenciosamente una característica. En pocas palabras: Capgo no puede actualizar code nativo, por lo que un dispositivo que ejecuta la construcción nativa antigua no puede ejecutar de manera segura un paquete que se construyó contra nuevos code nativos.

Cómo Capgo detecta la compatibilidad

Cuando sube un paquete — o ejecuta la comprobación manualmente — Capgo compara los paquetes nativos en su proyecto local (sus Capacitor/Cordova plugins y sus versiones) contra los paquetes nativos registrados para el paquete actualmente 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 incompatible nativo — esos cambios solo tienen efecto una vez que los usuarios instalen un nuevo binario nativo.

Verificar 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 a intercambiar los emojis por OK/FAIL (útil en los registros de CI), y --package-json / --node-modules a señalar los caminos correctos en un monorepo.

Obtenga un veredicto legible por máquina (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

Esté su pipeline de lanzamiento en cuarentena: envíe una actualización en vivo cuando imprima OTA, y active una compilación nativa cuando imprima native.

What significa una actualización incompatible para tus usuarios

Advertencia

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

On dispositivos que aún están ejecutando la versión nativa binaria antigua, la falta de la nativa __CAPGO_KEEP_0__ puede causar errores o características rotas — incluso si el actualizado se descargó y se aplicó “con éxito.” Esto es por qué una actualización en vivo puede ser en vivo y entregada, pero aún puede romper la aplicación para los usuarios existentes, y por qué __CAPGO_KEEP_1__ puede advertirte cuando un paquete incompatible se pone en vivo. __CAPGO_KEEP_0__’s, 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 corra, pero no es un sustituto para enviar una nativa __CAPGO_KEEP_0__ compatible — una incompatibilidad que causa un error más tarde, o que causa un error nativo, puede pasar por alto. ¿Cómo enviar cambios nativos de manera segura 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.

Publicar una nueva construcción nativa (la verdadera solución)

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

When a bundle needs new native code, build and submit a new binary to the App Store / Play Store (or rebuild with Capgo Cloud Build). Once users update the binary, the bundle’s native dependencies line up and the live update runs correctly.

Revertir si un paquete incompatible ya está en vivo

Si un paquete incompatible ya está activo en un canal, reemplazar el canal con la última versión compatible para detener su entrega hasta que se publique una versión nativa. Consulte Reversiones.

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 versión nativa:

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

Las subidas compatibles — y los 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 el flujo de construcción nativa del Capgo en lugar de eso; rechazar falla. (No se puede combinar con --ignore-metadata-check.)

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

Cuando usted hacer enviar el paquete nativo y el paquete juntos, coloque el canal en el metadata estrategia y subir con --auto-min-update-version. Capgo ejecuta el cheque de compatibilidad en cada subida y, cuando un paquete necesita nuevos nativos code, eleva el piso de actualización para que los dispositivos que no han instalado la construcción nativa correspondiente no lo 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

Las reglas de número de versión como --disable-auto-update major no son un sustituto — solo bloquean saltos de versión y nunca inspeccionan __CAPGO_KEEP_0__, por lo que un cambio nativo enviado en una versión menor o de parche todavía se envía. Utilice a substitute — they only block version jumps and never inspect native code, so a native change shipped in a minor or patch release still goes out. Use --fail-on-incompatible , que revisan sus paquetes nativos. --auto-min-update-versionConsulte

Version Targeting para obtener la completa lista de opciones de enfoque. Sección relacionada titulado “Relacionado”

Sección relacionada titulado “Relacionado”

Versión Dirigida

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

Reversiones

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

Tipos de Actualización

¿Cómo funcionan el retraso, las condiciones de retraso y el bloqueo de versión en conjunto?

CLI: paquete

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

Sigue adelante desde la compatibilidad nativa

Si estás utilizando Compatibilidad Nativa para mantener actualizaciones en vivo seguras, conecte con Versión de destino para enviar paquetes por versión nativa, Reversiones para recuperarse cuando un paquete incompatible se envía, Tipos de actualización para entender el bloqueo de versión de canal, y el Capgo CLI referencia de paquete para los comandos de compatibilidad y releaseType.