Compatibilidad nativa

Una actualización en vivo de Capgo reemplaza el paquete JavaScript de tu aplicación de manera instantánea, pero no puede cambiar la parte nativa de tu aplicación — los plugins de Cordova, dependencias nativas y 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 la plataforma nativa : __CAPGO_KEEP_0__ puede entregarlo, pero puede que se produzca un error o se comporte de manera inesperada en dispositivos que todavía están ejecutando la versión nativa más antigua. 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 Source guide: Capgo can still deliver it, but it may crash or misbehave on devices that are still running the older native build.

Esta página explica cómo Capgo detecta 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 nativa — agregar o eliminar un plugin, actualizar Capacitor o cambiar la configuración del proyecto nativo — deberá enviar un nuevo build binario a través del proceso de distribución habitual de la tienda de aplicaciones.

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 Aplicaciones / Tienda de Juegos. Contiene Capacitor, tus plugins nativos y 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 función. En pocas palabras: Capgo no puede actualizar code nativo, por lo que un dispositivo que ejecuta la versión nativa antigua no puede ejecutar de manera segura un paquete que se construyó contra code nativo nuevo.

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 (tus Capacitor/plugins de Cordova y sus versiones) con 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 nativamente — esos 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 repositorio monolítico.

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

Gare su pipeline de lanzamiento en esto: envíe una 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 incompatibilizado nativamente y lo estableces como la construcción activa de un canal, __CAPGO_KEEP_0__ block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo a dispositivos de ese canal. (Puedes convertir esto en una puerta dura con — ve --fail-on-incompatible Prevenir entregas incompatibles a continuación.) En dispositivos que aún ejecutan la

binaria nativa más antigua , la __CAPGO_KEEP_0__ nativa faltante puede causar errores o características rotas — incluso aunque la actualización se descargó y 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 usuarios existentes, y por qué __CAPGO_KEEP_1__ puede advertirte cuando un paquete incompatibilizado va en vivo.Prevent incompatible deliveries below. On devices still running the older native binary, 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. By default, detecting incompatibility does not block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, code will deliver it to devices on that channel. (You can turn this into a hard gate with — see below.)

Capgo’s rollback automático puede capturar un error de JavaScript lanzado antes notifyAppReady() ejecuta, pero no es un sustituto para enviar cambios nativos compatibles con code — una incompatibilidad que hace que el sistema se caiga más tarde, o se caiga nativamente, puede pasar por alto.

Cómo enviar cambios nativos de manera segura

Publicar un nuevo build nativo (la solución real)

Cuando una paquetería necesita nuevos code nativos, construya y envíe un nuevo binario a la Tienda de Mac / Tienda de Android (o reconstruya con Capgo Cloud Build). Una vez que los usuarios actualicen el binario, las dependencias nativas de la paquetería se alinean y el actualización en vivo se ejecuta correctamente.

Revertir si una paquetería incompatible ya está en vivo

Si una paquetería incompatible ya está activa en un canal, reemplaza el canal con la última construcción compatible para detener su servicio hasta que el build nativo esté disponible. Consulte Reversiones.

Prevenir envíos incompatibles

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

Fallar la subida 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 subida 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 Capgo Builder; declinar 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 de construcción nativa y el paquete juntos, poner el canal en la metadata estrategia y subir con --auto-min-update-version. Capgo realiza la comprobación 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

Reglas de número de versión como --disable-auto-update major son Not un sustituto — solo bloquean los saltos de versión y nunca inspeccionan el __CAPGO_KEEP_0__ nativo, 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

Versión de destino para obtener la completa lista de opciones de destino. Sección relacionada titulado ‘Relacionado’

Versión de destino

Revertir

Revertir

Revertir

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

Actualizar Tipos

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

CLI: paquete

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

Sigue desde la compatibilidad nativa

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