Comportamiento de actualización

Cuando lanzas una actualización para tu app con Capgo, lo ideal es que tus usuarios la reciban cuanto antes. Pero tampoco quieres interrumpir su experiencia obligándolos a esperar una descarga o a reiniciar la app en plena sesión.

El comportamiento de actualización de Capgo busca un equilibrio entre entregar actualizaciones rápido y minimizar interrupciones para tus usuarios.

Flujo de actualización por defecto

Por defecto, así es como Capgo gestiona las actualizaciones de la app:

1. Cuando la app pasa a primer plano, el plugin de Capgo comprueba si hay una nueva actualización disponible. Mientras la app esté abierta, también vuelve a comprobar mediante un temporizador controlado por periodCheckDelay (por defecto 10 minutos).

2. Si encuentra una actualización, se descarga en segundo plano mientras el usuario sigue usando la versión actual de la app.

3. Una vez completada la descarga, Capgo espera a que el usuario pase la app a segundo plano.

4. La próxima vez que el usuario pase la app a primer plano, estará ejecutando la versión actualizada.

Este flujo garantiza que los usuarios siempre usen la última versión de tu app, sin interrupciones por prompts de actualización ni esperas por descargas.

Consejo

Capgo busca actualizaciones cada vez que la app pasa al primer plano y con un temporizador recurrente mientras la app permanece abierta. periodCheckDelay controla ese intervalo (por defecto 10 minutos).

¿Por qué este enfoque?

Aplicar actualizaciones en segundo plano o al cerrar la app tiene varios beneficios clave para la experiencia de usuario:

• Los usuarios no se ven interrumpidos por prompts de actualización ni tienen que esperar descargas en medio de una sesión.

• Las actualizaciones se aplican sin fricción entre sesiones, así que la app siempre se siente actualizada al abrirla.

• Puedes lanzar actualizaciones con frecuencia sin preocuparte por interrumpir a los usuarios activos.

La principal desventaja es que si un usuario pone la app en segundo plano y la reanuda rápidamente, podría perder el estado no guardado, ya que la actualización se aplicó entre ambas acciones.

Para mitigar esto, recomendamos:

• Guardar el estado con frecuencia y restaurarlo sin problemas cuando la app se reanude.

• Evitar actualizaciones muy frecuentes que modifiquen gran parte del estado de la app.

• Considera personalizar el comportamiento de la actualización para flujos sensibles (ver abajo).

Personaliza cuándo se aplican las actualizaciones

En algunos casos, quizás quieras tener más control sobre exactamente cuándo se aplica una actualización. Por ejemplo, puede que quieras asegurarte de que un usuario termine un flujo en curso antes de actualizar, o coordinar una actualización de la app con un cambio del lado del servidor.

Capgo proporciona una setDelay función que te permite especificar las condiciones que deben cumplirse antes de instalar una actualización:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

await CapacitorUpdater.setMultiDelay({
  delayConditions: [
    {
      kind: 'date',
      value: '2023-06-01T00:00:00.000Z',
    },
    {
      kind: 'background',
      value: '60000',
    },
  ],
});

Este ejemplo retrasaría la instalación de una actualización hasta después del 1 de junio de 2023 Y hasta que la app haya estado en segundo plano durante al menos 60 segundos.

Las condiciones de retraso disponibles son:

• date: Espera hasta después de una fecha/hora específica para aplicar la actualización.
• background: Espera un tiempo mínimo tras pasar la app a segundo plano para aplicar la actualización.
• nativeVersion: Espera a que se instale un binario nativo con una versión mínima antes de aplicar la actualización.
• kill: Espera hasta el próximo evento de cierre de la app para aplicar la actualización.

Puedes combinar estas condiciones para controlar con precisión cuándo se instala una actualización.

Peligro

Ten en cuenta que la kill condición actual desencadena la actualización tras el primer evento de cierre, no en el siguiente evento en segundo plano como las demás condiciones. Esta inconsistencia se corregirá en una próxima versión.

Aplicar actualizaciones de inmediato

Para actualizaciones críticas o apps con un estado muy simple, es posible que quieras aplicar una actualización en cuanto se descargue, sin esperar a un evento en segundo plano o de cierre. Capgo lo admite mediante la autoUpdate política en tu configuración de Capacitor.

Requisitos para aplicar de inmediato: --delta, autoSplashscreen y SplashScreen

"atInstall", "onLaunch", y "always" aplica la actualización mientras el usuario espera. Usa Actualizaciones delta para que solo se descarguen los archivos modificados. Subir un zip completo ralentiza la experiencia.

Estos modos también requieren @capacitor/splash-screen y autoSplashscreen: true con SplashScreen.launchAutoHide: false. Sin el plugin splash, el usuario puede ver un parpadeo o una UI desactualizada mientras se aplica la actualización.

Cuando autoUpdate is set to "atInstall", "onLaunch", o "always" en tu capacitor.config, el CLI lo detecta. En entornos no interactivos envía actualizaciones Delta automáticamente, y en entornos interactivos te pide confirmación antes de subir. La configuración directUpdate legacy aún se detecta. Usa --no-delta para forzar la subida de un bundle completo.

npx @capgo/cli@latest bundle upload --delta

autoUpdate se configura en tu capacitor.config.ts archivo, no en JavaScript code. Admite estos valores:

• false o 'off': Disable automatic update checks
• true o 'atBackground' (predeterminado): Comprueba y descarga automáticamente en cada comprobación en primer plano y aplica la actualización la próxima vez que la app pase a segundo plano
• 'atInstall': Aplicar inmediatamente solo tras una instalación limpia o actualización de la tienda; de lo contrario, usar "atBackground" comportamiento
• 'onLaunch': Se aplica inmediatamente solo cuando la app vuelve al primer plano desde un estado cerrado (cold start). Después de esa primera comprobación, recurre a "atBackground" comportamiento
• 'always': Comprueba en cada transición al primer plano y aplica inmediatamente cuando haya una actualización disponible
• 'onlyDownload': Comprueba y descarga automáticamente, emite updateAvailable, y nunca establece el siguiente bundle ni aplica una actualización automáticamente

Prueba un Native Build sin Live Updates

Ver Prueba Native Builds sin Live Updates para las salvaguardas de configuración de native-version, channel-policy y CI.

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'always', // or 'atInstall' for updates only on app install/update
      autoSplashscreen: true,
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false, // Required for instant apply with autoSplashscreen
    },
  },
};

export default config;

Nota

Importante: los modos de aplicación instantánea solo aplican actualizaciones cuando el plugin realmente las comprueba. Por defecto, las comprobaciones se ejecutan cuando la app pasa a primer plano y mediante un temporizador repetitivo mientras la app permanece abierta. periodCheckDelay controla ese intervalo (por defecto 10 minutos).

Con autoUpdate: 'always', Capgo comprueba en cada transición a primer plano y aplica una actualización inmediatamente en cuanto se completa la descarga durante esa comprobación, incluso si el usuario está usando activamente la app. Las comprobaciones periódicas controladas por periodCheckDelay pueden desencadenar el mismo comportamiento de aplicación inmediata mientras la app permanece abierta.

Ten en cuenta que, dado que autoUpdate es una configuración nativa, los modos de aplicación instantánea requieren un manejo adicional en tu JavaScript code.

Precaución

Los modos de aplicación instantánea requieren @capacitor/splash-screen y autoSplashscreen: true. Set launchAutoHide: false en la configuración de SplashScreen (como se muestra arriba) para que la pantalla de inicio siga visible hasta que la actualización termine.

Descarga automática sin aplicar

Si quieres que Capgo compruebe y descargue actualizaciones automáticamente, pero nunca las aplique automáticamente, usa autoUpdate: 'onlyDownload':

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'onlyDownload',
    },
  },
};

En este modo, el plugin emite updateAvailable después de que se descarga un bundle. Tu app puede decidir entonces cuándo llamar a CapacitorUpdater.set() o mostrar su propio prompt de actualización.

Gestión automática del Splashscreen

Modos de aplicación instantánea ("atInstall", "onLaunch", "always") require autoSplashscreen y @capacitor/splash-screen (disponible desde la versión 7.6.0). Instala el plugin y mantén el splash visible hasta que Capgo lo oculte:

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'always', // or 'atInstall'
      autoSplashscreen: true, // Automatically hide splashscreen
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false,
    },
  },
};

Cuando autoSplashscreen está activado:

• El plugin oculta automáticamente el splashscreen cuando se aplica una actualización
• El plugin oculta automáticamente el splashscreen cuando no se necesita ninguna actualización
• No necesitas escuchar manualmente appReady eventos ni llamar a SplashScreen.hide()

Tareas extra tras ocultar el splash

Mantén autoSplashscreen: true. Si necesitas lógica adicional cuando la actualización esté lista, escucha también appReady . No omitas el plugin de splash ni autoSplashscreen para esto:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

CapacitorUpdater.addListener('appReady', () => {
  // Update is applied. autoSplashscreen already hid the splash.
});

CapacitorUpdater.notifyAppReady();

El appReady el evento se dispara una vez que la app ha terminado de inicializarse y aplicar las actualizaciones pendientes.

Configurar keepUrlPathAfterReload a true cuando se usa un modo de aplicación instantánea. Esto preserva la ruta de URL actual cuando la app se recarga debido a una actualización.

Usar un modo de aplicación instantánea puede ser útil para entregar correcciones críticas de errores o parches de seguridad, pero conlleva algunas compensaciones:

• El usuario puede ver un breve parpadeo o estado de carga al aplicar la actualización si @capacitor/splash-screen is missing or autoSplashscreen no está habilitado.
• Si la actualización modifica el estado o la interfaz de la app, el usuario puede ver un cambio disruptivo a mitad de la sesión.
• La ubicación del usuario en la app puede perderse si keepUrlPathAfterReload no está configurado, lo que podría desorientarlo.
• Deberás manejar cuidadosamente el guardado y la restauración del estado para garantizar una transición fluida.

Si habilitas la aplicación instantánea, te recomendamos:

• Subiendo con npx @capgo/cli@latest bundle upload --delta para que la descarga no ralentice la experiencia del usuario.
• Instalar @capacitor/splash-screen y configurar autoSplashscreen: true con launchAutoHide: false.
• Configuración keepUrlPathAfterReload a true para preservar la ubicación del usuario en la app.
• Guardar y restaurar el estado de la app según sea necesario para evitar perder el progreso del usuario.
• Prueba a fondo el comportamiento de actualizaciones de tu app para evitar transiciones bruscas, pérdida de estado o cambios de ubicación confusos.

En la mayoría de los casos, el comportamiento de actualización predeterminado ofrece el mejor equilibrio entre entregar actualizaciones rápidamente y minimizar la interrupción. Pero para apps con necesidades específicas, Capgo ofrece la flexibilidad para personalizar cuándo y cómo se aplican las actualizaciones.

Continuar desde Comportamiento de actualización

Si estás usando Comportamiento de actualización para planificar la entrega de live update, conéctalo con Live Updates de Capgo para el flujo de trabajo del producto en Capgo Live Updates, Resumen para el detalle de implementación en Overview, Funcionalidades para el detalle de implementación en Features, Tipos de actualización para los detalles de implementación en Update Types, y Primeros pasos para los detalles de implementación en Getting Started.