Comportamiento de Actualización

Cuando liberes una actualización a tu aplicación Capgo, probablemente querrás que tus usuarios la reciban lo antes posible. Pero también no quieres interrumpir su experiencia obligándolos a esperar a que se descargue o reinicien la aplicación en medio de una sesión.

Capgo’s comportamiento de actualización está diseñado para encontrar un equilibrio entre entregar actualizaciones de manera rápida y minimizar la interrupción de tus usuarios.

Flujo de actualización por defecto

Por defecto, aquí es cómo Capgo maneja las actualizaciones de aplicaciones:

1. Al iniciar la aplicación, el plugin Capgo verifica si hay una nueva actualización disponible.

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

3. Una vez que se complete la descarga, Capgo espera a que el usuario ponga la aplicación en segundo plano o la elimine por completo.

4. Cuando el usuario lance la aplicación por primera vez, estarán ejecutando la versión actualizada.

Este flujo garantiza que los usuarios siempre estén ejecutando la última versión de su aplicación, sin que nunca sean interrumpidos por solicitudes de actualización o obligados a esperar a que se descarguen actualizaciones.

Consejo

Capgo también verifica actualizaciones cuando la aplicación vuelve a ejecutarse desde el fondo, por lo que los usuarios recibirán actualizaciones incluso si no cierran completamente la aplicación.

¿Por qué este enfoque?

Aplicar actualizaciones en un evento de fondo o de cierre tiene algunos beneficios clave para la experiencia del usuario:

• Los usuarios no son interrumpidos por solicitudes de actualización o obligados a esperar a que se descarguen actualizaciones en medio de una sesión.

• Las actualizaciones se aplican de manera fluida entre sesiones, por lo que la experiencia de iniciar la aplicación siempre es fresca.

• Puede entregar actualizaciones con frecuencia sin preocuparse por interrumpir a los usuarios activos.

El principal inconveniente es que si un usuario envía a segundo plano y vuelve rápidamente a su aplicación, puede perder cualquier estado no guardado desde que se aplicó la actualización entre esas acciones.

Para mitigar esto, recomendamos:

• Guardar el estado con frecuencia y restaurarlo de manera suave cuando la aplicación se reanude.

• Evitar actualizaciones muy frecuentes que modifican grandes partes del estado de la aplicación.

• Considerar personalizar el comportamiento de la actualización para flujos sensibles (consulte a continuación).

Personalizar Cuando Se Aplican Las Actualizaciones

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

Capgo proporciona una setDelay función que le permite especificar condiciones que deben cumplirse antes de que se instale 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 la aplicación ha estado en segundo plano durante al menos 60 segundos.

Las condiciones de retraso disponibles son:

• date: Esperar hasta después de una fecha/hora específica para aplicar la actualización.
• background: Espera un mínimo de duración después de que la aplicación se ponga en 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 eliminación de la aplicación 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 hace que la actualización se aplique después del primer evento de eliminación, no del próximo evento de segundo plano como las otras condiciones. Esta inconsistencia se corregirá en una futura versión.

Aplicar Actualizaciones Inmediatamente

Para actualizaciones críticas o aplicaciones con un estado muy simple, es posible que desees aplicar una actualización tan pronto como se descargue, sin esperar a un evento de segundo plano o eliminación. Capgo lo soporta mediante la directUpdate opción de configuración.

Recomendado: Utilice actualizaciones de Delta (Manifiesto) con Actualización Directa

Cuando utilice directUpdate, nosotros recomendamos fuertemente habilitar Actualizaciones de Delta (manifiesto) para minimizar los tiempos de descarga y mejorar la experiencia del usuario. Las actualizaciones de Delta (manifiesto) solo descargan archivos modificados en lugar de todo el paquete, lo cual es especialmente importante cuando se aplican actualizaciones de inmediato mientras los usuarios están utilizando activamente su aplicación.

¿Por qué esto importa para Actualizaciones Directas:

• Actualizaciones más rápidas: Descargas más pequeñas significan que las actualizaciones se completan rápidamente, reduciendo el tiempo que los usuarios ven pantallas de carga
• Mejor experiencia móvil: Usuarios en redes móviles o conexiones más lentas no enfrentarán tiempos de espera largos
• Menor uso de ancho de banda: Solo se descargan archivos modificados, lo que ahorra datos tanto para ti como para tus usuarios

Cuando directUpdate está habilitado en tu capacitor.config, el CLI lo detecta. En entornos no interactivos envía actualizaciones de Delta (manifesto) automáticamente, y en entornos interactivos te pide confirmación antes de subir. Utiliza --no-delta para forzar una subida de paquete completa.

Para habilitar actualizaciones de Delta (manifesto), simplemente utiliza la --delta flag al subir paquetes:

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

Aprende más en el Actualizaciones (manifesto) Documentación de actualizaciones.

directUpdate se establece en tu capacitor.config.ts archivo, no en JavaScript code. Soporta tres valores:

• false (por defecto): Nunca hacer actualizaciones directas (utilizar el comportamiento predeterminado: descargar al inicio, establecer cuando se ponga en segundo plano)
• 'atInstall': Actualizar directamente solo cuando la aplicación esté instalada, actualizada desde la tienda, de lo contrario actúa como directUpdate = false
• 'onLaunch': Actualizar directamente solo cuando la aplicación esté instalada, actualizada desde la tienda o después de que se cierre la aplicación, de lo contrario actúa como directUpdate = false
• 'always': Actualizar directamente en todos los casos anteriores (aplicación instalada, actualizada desde la tienda, después de que se cierre la aplicación o se reanude la aplicación), nunca actuar como directUpdate = false
• true (obsoleto): Lo mismo que 'always' para compatibilidad hacia atrás

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

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      directUpdate: 'always', // or 'atInstall' for updates only on app install/update
      autoSplashscreen: true, // NEW: Automatically handle splashscreen
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false, // Still required when using directUpdate
    },
  },
};

export default config;

Nota

Importante: directUpdate solamente se aplican actualizaciones cuando la aplicación verifica realmente. Por defecto, esto solo ocurre al iniciar la aplicación o al reanudar desde el fondo. Tenga en cuenta que periodCheckDelay no es compatible con directUpdate.

Con directUpdate habilitado, Capgo aplicará inmediatamente una actualización tan pronto como se complete el descarga durante una verificación de actualizaciones, incluso si el usuario está utilizando activamente la aplicación. Sin la verificación periódica habilitada, esto significa que las actualizaciones solo se aplicarán cuando la aplicación inicie o reanude desde el fondo.

Tenga en cuenta que porque directUpdate es una configuración nativa, requiere algunos manejo adicional en su JavaScript code.

Advertencia

Al utilizar directUpdate, debe establecer launchAutoHide: false en la configuración de SplashScreen (como se muestra arriba) para evitar que la pantalla de bienvenida se oculte automáticamente. Esto garantiza que tenga control total sobre cuándo se oculta la pantalla de bienvenida después de que se complete el proceso de actualización.

Gestión Automática de Pantalla de Presentación

Para hacerlo directUpdate más fácil de usar, Capgo ofrece una autoSplashscreen opción que automatiza la ocultación de la pantalla de presentación para usted (disponible desde la versión 7.6.0):

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

Cuando autoSplashscreen está habilitado:

• El plugin oculta automáticamente la pantalla de presentación cuando se aplica una actualización
• El plugin oculta automáticamente la pantalla de presentación cuando no se necesita una actualización
• No necesita escuchar manualmente appReady los eventos o llamar a SplashScreen.hide()

Gestión Manual de Pantalla de Presentación

Si prefieres tener control manual o necesitas lógica personalizada, puedes desactivar autoSplashscreen y manejarlo tú mismo:

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

CapacitorUpdater.addListener('appReady', () => {
  // Hide splash screen
  SplashScreen.hide();
});

CapacitorUpdater.notifyAppReady();

El appReady evento se dispara una vez que la aplicación ha finalizado la inicialización y la aplicación de cualquier actualización pendiente. Este es el punto en el que es seguro mostrar la interfaz de usuario de tu aplicación, ya que garantiza que el usuario verá la última versión.

Además de manejar el appReady evento, recomendamos establecer la opción de configuración keepUrlPathAfterReload cuando se utiliza true Este preserva la ruta de la URL actual cuando la aplicación se recarga debido a una actualización, lo que ayuda a mantener la ubicación del usuario en la aplicación y reduce la confusión. directUpdatetargetLanguage

Si no manejas el appReady y estableces keepUrlPathAfterReload al utilizar directUpdateel usuario puede ver brevemente una versión desactualizada de la aplicación, ser devuelto a la ruta inicial o ver un destello mientras se aplica la actualización.

Usar directUpdate puede ser útil para entregar parches de seguridad críticos o parches de bugs, pero conlleva algunos tradeofos:

• El usuario puede ver un destello breve o un estado de carga mientras se aplica la actualización si no manejas correctamente la pantalla de bienvenida (ya sea con autoSplashscreen o manejo manual del appReady evento).
• Si la actualización modifica el estado de la aplicación o la interfaz de usuario, el usuario puede ver un cambio disruptivo en medio de una sesión.
• La ubicación del usuario en la aplicación puede estar perdida si keepUrlPathAfterReload no está configurado, lo que puede desorientarlo.
• Deberá manejar con cuidado la conservación y restauración del estado para asegurar una transición suave.

Si habilita directUpdate, recomendamos:

• Usar autoSplashscreen: true para la configuración más sencilla, o manejar manualmente el appReady evento si necesita lógica personalizada.
• Configurar keepUrlPathAfterReload a true para mantener la ubicación del usuario en la aplicación.
• Guardar y restaurar el estado de la aplicación según sea necesario para evitar perder el progreso del usuario.
• Pruebas exhaustivas del comportamiento de actualización de la aplicación para asegurarse de que no haya transiciones bruscas, pérdida de estado o cambios de ubicación desorientadores.

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