Compatibilidad nativa

A Capgo actualización en vivo reemplaza el paquete de JavaScript de tu aplicación JavaScript bundle de inmediato, pero no puede cambiar la parte nativa de tu aplicación — los plugins __CAPGO_KEEP_0__/Cordova, las dependencias nativas y la configuración del proyecto nativo que se compilan en el binario instalado. native 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 que no tiene el binario instalado. Cuando un nuevo paquete espera __CAPGO_KEEP_1__ nativos que el binario instalado no tiene, el paquete es: Capgo can still deliver it, but it may crash or misbehave on devices that are still running the older native build.

: Capgo puede entregarlo, pero puede que se caiga o se comporte mal en dispositivos que todavía están ejecutando la construcción nativa más antigua.

Nota

Live updates are limited to JavaScript bundle changes. If you need to update native code — adding or removing a plugin, upgrading Capacitor, or changing native project configuration — you’ll need to submit a new binary build through the usual app-store distribution process.

Las actualizaciones en vivo están limitadas a cambios en el paquete de JavaScript. Si necesitas actualizar __CAPGO_KEEP_0__ nativo — agregando o eliminando un plugin, actualizando __CAPGO_KEEP_1__ o cambiando la configuración del proyecto nativo — necesitarás enviar un nuevo build binario a través del proceso de distribución habitual de la tienda de aplicaciones.

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 puro empaquetados en ese resultado, envíelo como actualización en vivo.

Utilice una versión nativa de la aplicación cuando un cambio actualice capacitor.config.ts, 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 ¿o

antes de que los dispositivos instalados puedan utilizarlo, trátelo como nativo.	Ship with Capgo OTA?	¿Envía con __CAPGO_KEEP_0__ OTA?
¿Por qué?	HTML, CSS, JavaScript de la aplicación, imágenes, fuentes y otros activos de compilación web	Sí
Paquetes de cambios de JavaScript puro empaquetados en tu salida web	Sí	El JavaScript generado forma parte del paquete web.
capacitor.config.ts cambios	No	Capacitor se lee en la configuración 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 de las tiendas.

Plugins de cliente por pila

Capgo envía actualizadores clientes 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

Las comprobaciones de compatibilidad nativa se aplican sin importar el plugin de 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:

• The binario nativo los usuarios instalan desde la Tienda de Aplicaciones / Tienda de Juegos. Contiene Capacitor, tus plugins nativos, y la configuración nativa.
• The paquete de JavaScript (tu 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 quebrante silenciosamente una función. En pocas palabras: Capgo no puede actualizar code nativo, por lo que un dispositivo que ejecuta la construcción nativa antigua no puede ejecutar seguramente un paquete que se construyó contra nuevos code nativos.

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/Cordova plugins y sus versiones) con los paquetes nativos registrados para el paquete actualmente vivo en el canal:

• Si coinciden, el cambio es solo JavaScript y seguro de 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.

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 que está viva 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 los registros de CI), y --package-json / --node-modules para señalar 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

Bloquear su pipeline de lanzamiento en esto: enviar una actualización en vivo cuando imprima OTAy desencadenar una compilación nativa cuando imprima native.

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

Cuidado

Por defecto, detectar incompatibilidad no bloquea la subida — si sube un paquete incompatibilidad nativa y lo establece como la compilació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 los dispositivos en ese canal. (Puede convertir esto en una puerta dura con) — vea --fail-on-incompatible Incompatibilidad Prevenir envíos incompatibles abajo.

En dispositivos que aún están ejecutando la binaria nativa 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 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 puede advertirte cuando un paquete incompatible se pone en vivo.

Capgo’s devolución automática no 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.

pero no es un sustituto para enviar nativa __CAPGO_KEEP_0__ compatible — una incompatibilidad que causa errores más tarde, o errores nativos, puede pasar por alto.

Título de la sección “Cómo enviar cambios nativos de manera segura”

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

Revertir si un paquete incompatible ya está en vivo

Si un paquete incompatible ya está activo en un canal, reemplaza el canal con la última versión compatible para evitar servirlo hasta que esté disponible la compilación nativa. Consulte Reversiones.

Prevenir entregas 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 una salida no cero y no se envía nada — por lo tanto, tu pipeline te impide 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

subidas 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; 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 subida de referencia. Mantén la bandera en el CI de actualización OTA diaria. Flujo de trabajo completo del canal: Flujo de trabajo de canal nativo + OTA.

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

Cuando usted haga envíe la construcción nativa 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 construcción nativa code, eleva el piso de actualización para que los dispositivos que no han instalado la construcció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

Las 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 código nativo __CAPGO_KEEP_0__, por lo que un cambio nativo enviado en una versión menor o de parche todavía se envía. Use 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 Ver --auto-min-update-versionCompatibilidad de versión

para obtener el conjunto completo de opciones de targeting. Relacionado Sección titulada “Relacionado”

Flujo de trabajo nativo + OTA

, y cómo enviar una base nativa intencional.

Flujo de trabajo nativo + OTA --fail-on-incompatibleFlujo de trabajo nativo + OTA

Auto OTA o Nativo

Alambre bundle releaseType en GitHub Acciones o GitLab para que CI elija la actualización en vivo frente a Capgo Compilación.

Alcance de Versión

contexto: Página/área: Página de marketing de soluciones de Capgo. Rol: Título de sección o página. Visto en: página de soluciones/alcance-de-versión.astro. Clave de mensaje `solutions_version_targeting_title` (Título de Soluciones de Alcance de Versión). | Página/área: Página de marketing de soluciones de Capgo. Rol: Etiqueta de IU corta o elemento de navegación. Visto en: página de soluciones/alcance-de-versión.astro. Clave de mensaje `solutions_version_targeting` (Soluciones de Alcance de Versión).

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 se publicó un paquete incompatible.

Tipos de Actualizaciones

CLI: bundle

__CAPGO_KEEP_0__: paquete

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

Si estás utilizando Compatibilidad nativa para mantener las actualizaciones en vivo seguras, conecta con Compatibilidad de versión contexto: Página/área: Página de marketing de soluciones de Capgo. Rol: Título de sección o página. Visto en: página de soluciones/versión-targeting.astro. Clave de mensaje `solutions_version_targeting_title` (Título de soluciones de versión de targeting). | Página/área: Página de marketing de soluciones de Capgo. Rol: Etiqueta de IU corta o elemento de navegación. Visto en: página de soluciones/versión-targeting.astro. Clave de mensaje `solutions_version_targeting` (Soluciones de versión de targeting). para enviar paquetes por versión nativa, Reversiones para recuperar cuando un paquete incompatible se envía, Tipos de actualizaciones Capgo CLI bundle reference __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ referencia de paquete de compatibilidad y tipo de lanzamiento