Compatibilidad nativa

Un Capgo live update reemplaza tu aplicación’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:Puede que Capgo siga entregándolo, pero puede que se caiga o comporte mal en dispositivos que siguen 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 paquetes de JavaScript. Si necesitas actualizar code — agregando o eliminando un plugin, actualizando Capacitor o cambiando la configuración del proyecto nativo — debes enviar un nuevo build binario a través del proceso de distribución de la tienda de aplicaciones habitual.

TLDR: OTA o nativa?

Capgo puede enviar archivos desde el carpeta de compilación web generada. Si el cambio solo afecta a HTML, CSS, JavaScript, activos o paquetes de JavaScript pura bundeados en esa salida, envíelo como un live update.

Use a native app release when a change updates capacitor.config.ts, 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 before installed devices can use it, treat it as native.

Change	Envíe actualizaciones con Capgo OTA?	Why
HTML, CSS, app JavaScript, images, fonts, and other web build assets	Yes	Se cargan desde el paquete web en tiempo de ejecución.
Se cargan desde el paquete web en tiempo de ejecución.	Sí	El JavaScript generado forma parte del paquete web.
capacitor.config.ts Cambios	No	Capacitor config is read into the native app at build time.
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	Existing users need a new binary from the stores.

Plugins de cliente por pila

Capgo ships dedicated updater clients for each hybrid runtime:

Plugin	Usar cuando
@capgo/capacitor-updater	Capacitor aplicaciones iOS/Android
@capgo/cordova-updater	Aplicaciones 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 configuración nativa.
• El paquete de JavaScript (tu aplicación web) que Capgo puede actualizar por aire.

A live update swaps only the JavaScript layer. If that new JavaScript calls a native plugin or API that isn’t compiled into the installed binary, the call fails at runtime — which can crash the app or silently break a feature. Put simply: Capgo cannot update native code, so a device running the old native build can’t safely run a bundle that was built against new native code.

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 en JavaScript y seguro para enviar por aire.
• Si se agregó, eliminó o cambió la versión de un plugin, el paquete es native-incompatible — esos cambios solo tienen efecto una vez que los usuarios instalen un nuevo binario nativo.

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 Añadir para cambiar los emojis por OK/FAIL (útil en registros de CI), y --package-json / --node-modules to point at the right paths in a monorepo.

Obtén un veredicto legible por máquina (CI)

Para las pipelines bundle releaseType reduce la comprobación a 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

Gate your release pipeline on this: ship a live update when it prints OTAy desencadena una compilación nativa cuando lo imprime. native.

What an incompatible update means for your users

Advertencia

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 Prevenir entregas incompatibles below.)

En dispositivos que todavía están ejecutando el binario nativo más antiguo, la falta de un code nativo 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 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.

How to ship native changes safely

Publish a new native build (the real fix)

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 el build nativo esté disponible. 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 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 impida que publiquemos actualizaciones OTA en silencio que no pueden tener efecto hasta que los usuarios instalen una compilación nativa:

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

subidas compatibles — y casos en los que el chequeo 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 de Capgo para compilación nativa; rechazar falla. (No se puede combinar con --ignore-metadata-check.)

Consejo

Cuando tú intencionalmente necesitas 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 referencia. Mantenga la bandera en OTA CI diaria. Flujo de canal completo: Flujo de trabajo de canal nativo + OTA.

Entregar 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 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

Versión-número reglas como --disable-auto-update major no son una sustituta — 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. Use --fail-on-incompatible o --auto-min-update-version, que compruebe sus paquetes nativos.

o 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, cuando mantener

, y cómo enviar una base nativa intencional.

Alambre bundle releaseType en 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 el retraso, las condiciones de retraso y el bloqueo de versión en conjunto.

CLI: bundle

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

Sigue adelante desde la compatibilidad nativa

Si estás utilizando Nivel de compatibilidad to keep live updates safe, connect it with Objetivo de versión Ruta los paquetes por versión nativa. Rollbacks recuperar cuando se envía un paquete incompatible. Tipos de Actualizaciones para entender el bloqueo de la versión del canal y Capgo CLI referencia de paquete __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ referencia de paquete