Compatibilidad nativa

A Capgo live update replaces your app’s paquete de JavaScript instantáneamente, pero no puede cambiar la nativa 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 native-incompatible: Capgo puede entregarlo, pero puede provocar un error o comportarse de manera inesperada en dispositivos que siguen ejecutando la versión nativa anterior.

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 paquetes de JavaScript. Si necesitas actualizar code nativo — agregar o eliminar un plugin, actualizar Capacitor o cambiar la configuración del proyecto nativo — debes enviar un nuevo build binario a través del proceso de distribución habitual de tiendas de aplicaciones.

TLDR: OTA o nativo?

Capgo puede enviar archivos desde la carpeta de compilación web generada. Si el cambio solo afecta a HTML, CSS, JavaScript, activos o paquetes de JavaScript puro empaquetados en ese resultado, envíelo como un live update.

Use un lanzamiento de aplicación nativa cuando un cambio actualiza capacitor.config.tso la configuración de plugin almacenada en Capacitor config, plugins nativos o dependencias, 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, trátelo como nativo.

Cambio	¿Envía con Capgo OTA?	¿Por qué
HTML, CSS, JavaScript de la aplicación, imágenes, fuentes y otros activos de compilación web	Sí	Son cargados desde el paquete web en tiempo de ejecución.
Cambios en paquetes de JavaScript puro empaquetados en su salida web	Sí	El JavaScript generado forma parte del paquete web.
capacitor.config.ts los cambios	No	La configuración de Capacitor 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 de las tiendas.

Los plugins del cliente por pila

Capgo envía clientes de actualizaciones dedicados para cada tiempo de ejecución híbrido:

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

Verificaciones de compatibilidad nativa se aplican sin importar el plugin del cliente — comparan las dependencias nativas registradas del paquete con la biblioteca instalada.

¿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, tus plugins nativos, y la configuración nativa.
• El paquete de JavaScript (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 quebrante 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 seguramente un paquete que se construyó contra code nativos nuevos.

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 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 incompatible con el nativo — 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 Agregar para cambiar los emojis por OK/FAIL (útil en los registros de CI), y --package-json / --node-modules punter a los caminos correctos en un repositorio monolítico.

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

Bloquee su pipeline de lanzamiento en esto: envíe un live update cuando imprima OTA, y desencadena una compilación nativa cuando lo imprime native.

¿Qué significa una actualización incompatible para tus 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 los dispositivos de ese canal. (Puedes convertir esto en una puerta dura con) --fail-on-incompatible — see Prevenir entregas incompatibles below.)

En dispositivos que todavía están ejecutando la binaria nativa más antigua, la falta de la nativa code puede causar errores o características rotas — incluso si el actualizado se descargó y se aplicó “con éxito.” Esto es por lo que un live update puede estar vivo y entregado, pero aún puede romper la aplicación para los usuarios existentes, y por qué Capgo puede advertirte cuando un paquete incompatible se pone en vivo.

Capgo’s el retorno automático puede atrapar 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

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

When un bundle necesita nuevos nativos code, construye y envía un nuevo binario a la Tienda de Aplicaciones / Tienda de Juegos (o reconstruye con Capgo Cloud Build). Una vez que los usuarios actualicen el binario, las dependencias nativas del bundle se alinean y el live update se ejecuta correctamente.

Revertir si un bundle incompatible ya está en vivo

Si un bundle incompatible ya está activo en un canal, reemplaza el canal con la última versión compatible para evitar servirlo hasta que se publique el build nativo. 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

Agrega la bandera a tu bundle upload Paso. Si los paquetes nativos del bundle no coinciden con la versión actualmente disponible del canal, el subir. 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

Compatibles — y casos en los que el cheque no se puede ejecutar (un nuevo canal, o no hay metadatos remotos) — pasan sin cambios. En una terminal interactiva ofrece en su lugar el flujo de construcción de Capgo para compilación nativa; declinar falla. (No se puede combinar con --ignore-metadata-check.)

Consejo

Cuando tú intentionally necesita un paquete que difiera de los paquetes nativos en vivo del canal (nuevo plugin, Capacitor actualización, y así sucesivamente), omitir --fail-on-incompatible Para esa carga de base. Mantenga la bandera en CI OTA diaria. Flujo de canal completo: Flujo de trabajo de Canal Nativo + Actualización OTA.

Flujo de trabajo de canal nativo + OTA 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 realiza la comprobación de compatibilidad en cada subida 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 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

Cuidado

Reglas de número de versión como --disable-auto-update major no son una sustitución — solo bloquean los saltos de versión y nunca inspeccionan el code nativo, por lo que un cambio nativo enviado en una versión menor o de parche todavía se envía. Use --fail-on-incompatible o --auto-min-update-version, comprueba tus paquetes nativos.

See Versión Dirigida para el conjunto completo de opciones de destino.

Related

Sección titulada “Relacionado”

Flujo de trabajo nativo + OTA --fail-on-incompatibleCanales de desarrollo/producto, cuándo mantener

, y cómo enviar una base nativa intencional.

Alambre bundle releaseType enviar a GitHub Acciones o GitLab para que CI capture live update vs Capgo Compilación.

Versión de destino

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

Rollbacks

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

Tipos de Actualizaciones

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

CLI: paquete

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

Sigue adelante desde compatibilidad nativa

If estás utilizando Compatibilidad nativa para mantener las actualizaciones en vivo seguras, conecta con Alcance de versión Para rutas de paquetes por versión nativa. Rollbacks recuperar cuando se envía un paquete incompatible. Tipos de Actualizaciones para entender la versión del canal bloqueada, y el Capgo CLI referencia del paquete para los comandos de compatibilidad y tipo de lanzamiento.