Comportement de mise à jour

Lorsque vous publiez une mise à jour pour votre application Capgo, vous souhaitez probablement que vos utilisateurs la reçoivent le plus rapidement possible. Mais vous ne voulez pas non plus interrompre leur expérience en les forçant à attendre un téléchargement ou à redémarrer l'application en pleine session.

Le comportement de mise à jour de Capgo est conçu pour équilibrer la rapidité de livraison et la minimisation des interruptions pour vos utilisateurs.

Flux de mise à jour par défaut

Par défaut, voici comment Capgo gère les mises à jour de l'application :

1. Lorsque l'application passe au premier plan, le plugin Capgo vérifie si une nouvelle mise à jour est disponible. Tant que l'application reste ouverte, il effectue également une nouvelle vérification via un timer répétitif contrôlé par periodCheckDelay (10 minutes par défaut).

2. Si une mise à jour est trouvée, elle est téléchargée en arrière-plan pendant que l'utilisateur continue d'utiliser la version actuelle de l'application.

3. Une fois le téléchargement terminé, Capgo attend que l'utilisateur mette l'application en arrière-plan.

4. La prochaine fois que l'utilisateur ramènera l'application au premier plan, il utilisera la version mise à jour.

Ce flux garantit que vos utilisateurs utilisent toujours la dernière version de votre application, sans jamais être interrompus par des prompts de mise à jour ou contraints d'attendre les téléchargements.

Astuce

Capgo recherche des mises à jour dès que l'application passe au premier plan et via un timer périodique tant que l'application reste ouverte. periodCheckDelay contrôle cet intervalle (10 minutes par défaut).

Pourquoi cette approche ?

Applying updates on a background or kill event has a few key benefits for user experience:

• Les utilisateurs ne sont pas interrompus par des prompts de mise à jour ou forcés d'attendre des téléchargements en pleine session.

• Les mises à jour s'appliquent de manière transparente entre les sessions, pour que l'expérience de lancement de l'app soit toujours optimale.

• Vous pouvez déployer des mises à jour fréquemment sans craindre de perturber vos utilisateurs actifs.

L'inconvénient principal est que si un utilisateur met l'app en arrière-plan et la relance rapidement, il peut perdre tout état non sauvegardé puisque la mise à jour a été appliquée entre ces deux actions.

Pour atténuer cela, nous recommandons de :

• Sauvegarder l'état fréquemment et le restaurer proprement lors de la reprise de l'application.

• Évitez les mises à jour trop fréquentes qui modifient de larges parties de l'état de l'app.

• Envisagez de personnaliser le comportement des mises à jour pour les flux sensibles (voir ci-dessous).

Personnaliser le moment d'application des mises à jour

Dans certains cas, vous pouvez vouloir plus de contrôle sur le moment exact où une mise à jour est appliquée. Par exemple, vous voulez peut-être vous assurer qu'un utilisateur termine un flux en cours avant la mise à jour, ou coordonner une mise à jour de l'app avec un changement côté serveur.

Capgo propose une setDelay fonction qui vous permet de spécifier les conditions à remplir avant l'installation d'une mise à jour :

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

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

Cet exemple retarderait l'installation d'une mise à jour jusqu'au 1er juin 2023 ET après que l'application a été mise en arrière-plan pendant au moins 60 secondes.

Les conditions de délai disponibles sont :

• date: Attendre une date/heure précise avant d'appliquer la mise à jour.
• background: Attendre une durée minimale après la mise en arrière-plan de l'app pour appliquer la mise à jour.
• nativeVersion: Attendre qu'un binaire natif avec une version minimale soit installé avant d'appliquer la mise à jour.
• kill: Attendez le prochain événement de fermeture de l'app pour appliquer la mise à jour.

Vous pouvez combiner ces conditions pour contrôler précisément le moment auquel une mise à jour est installée.

Danger

Notez que la kill condition déclenche actuellement la mise à jour après le premier événement de fermeture, et non après le prochain événement en arrière-plan comme les autres conditions. Cette incohérence sera corrigée dans une prochaine release.

Appliquer les mises à jour immédiatement

Pour les mises à jour critiques ou les apps avec un état très simple, vous pouvez appliquer une mise à jour dès son téléchargement, sans attendre un événement en arrière-plan ou de fermeture. Capgo le permet via la autoUpdate politique dans votre config Capacitor.

Requis pour l'application instantanée : --delta, autoSplashscreen et SplashScreen

"atInstall", "onLaunch", et "always" appliquer la mise à jour pendant l'attente utilisateur. Utilisez Mises à jour delta pour ne télécharger que les fichiers modifiés. Un upload de zip complet dégrade l'UX.

Ces modes nécessitent également @capacitor/splash-screen et autoSplashscreen: true par SplashScreen.launchAutoHide: false. Sans le plugin splash, l'utilisateur peut voir un scintillement ou une UI obsolète pendant que la mise à jour s'applique.

Quand autoUpdate est défini sur "atInstall", "onLaunch", ou "always" dans votre capacitor.config, le CLI le détecte. Dans les environnements non interactifs, il envoie automatiquement les mises à jour Delta, et dans les environnements interactifs, il vous demande de confirmer avant l'upload. Legacy directUpdate configuration est toujours détectée. Utilisez --no-delta pour forcer l'upload d'un bundle complet.

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

autoUpdate est défini dans votre fichier capacitor.config.ts , pas dans le code JavaScript. Il supporte ces valeurs :

• false ou 'off': Disable automatic update checks
• true ou 'atBackground' (par défaut) : Vérifier et télécharger automatiquement à chaque passage au premier plan, puis appliquer la mise à jour lors du prochain passage en arrière-plan
• 'atInstall': Appliquer immédiatement uniquement après une nouvelle installation ou une mise à jour native sur les stores ; sinon, utiliser "atBackground" comportement
• 'onLaunch': S'applique immédiatement uniquement lorsque l'app revient au premier plan après avoir été tuée (cold start). Après ce premier contrôle, revenez à "atBackground" comportement
• 'always': Vérifie à chaque passage au premier plan et applique immédiatement dès qu'une mise à jour est disponible
• 'onlyDownload': Vérifie et télécharge automatiquement, émet updateAvailable, et ne définit jamais le prochain bundle ni n'applique automatiquement de mise à jour

Tester un Native Build sans Live Updates

Consultez Tester les Native Builds sans live updates pour les protections de configuration native-version, channel-policy et 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;

Remarque

Important : les modes d'application immédiate n'appliquent les mises à jour que lorsque le plugin effectue réellement une vérification. Par défaut, les vérifications ont lieu quand l'application passe au premier plan et via un timer récurrent tant que l'application reste ouverte. periodCheckDelay contrôle cet intervalle (10 minutes par défaut).

Avec autoUpdate: 'always', Capgo vérifie à chaque passage au premier plan et applique immédiatement une mise à jour dès que le téléchargement se termine lors de cette vérification, même si l'utilisateur utilise activement l'application. Les vérifications périodiques sont contrôlées par periodCheckDelay peuvent déclencher le même comportement d'application immédiate tant que l'application reste ouverte.

Notez que, comme autoUpdate est une configuration native, les modes d'application immédiate nécessitent une gestion supplémentaire dans votre code JavaScript.

Attention

Les modes d'application instantanée nécessitent @capacitor/splash-screen et autoSplashscreen: true. Définissez launchAutoHide: false dans la configuration SplashScreen (comme illustré ci-dessus) pour que l'écran de démarrage reste visible jusqu'à la fin de la Live Update.

Téléchargement automatique sans appliquer

Si vous voulez que Capgo vérifie et télécharge les mises à jour automatiquement sans jamais les appliquer automatiquement, utilisez autoUpdate: 'onlyDownload':

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

Dans ce mode, le plugin émet updateAvailable après le téléchargement d'un bundle. Votre application peut ensuite décider quand appeler CapacitorUpdater.set() ou afficher son propre prompt de mise à jour.

Gestion automatique du SplashScreen

Modes d'application instantanée ("atInstall", "onLaunch", "always") requis autoSplashscreen et @capacitor/splash-screen (disponible depuis la version 7.6.0). Installez le plugin, puis gardez le splash visible jusqu'à ce que Capgo le masque :

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

Quand autoSplashscreen est activé :

• Le plugin masque automatiquement le splashscreen lorsqu'une mise à jour est appliquée
• Le plugin masque automatiquement le splashscreen lorsqu'aucune mise à jour n'est nécessaire
• Vous n'avez pas besoin d'écouter manuellement appReady les événements ou d'appeler SplashScreen.hide()

Travail supplémentaire une fois le splash masqué

Conservez autoSplashscreen: true. Si vous avez besoin d'une logique supplémentaire une fois la mise à jour prête, écoutez appReady également. Ne sautez pas le plugin splash ni autoSplashscreen pour cela :

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

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

CapacitorUpdater.notifyAppReady();

Le appReady l'événement se déclenche une fois que l'application a fini de s'initialiser et d'appliquer les mises à jour en attente.

Définissez keepUrlPathAfterReload vers true lors de l'utilisation d'un mode instant apply. Cela conserve le chemin d'URL actuel lorsque l'application est rechargée suite à une mise à jour.

L'utilisation du mode application instantanée peut être utile pour déployer des correctifs de bugs critiques ou des patchs de sécurité, mais cela implique certains compromis :

• L'utilisateur peut voir un bref scintillement ou un état de chargement lors de l'application de la mise à jour si @capacitor/splash-screen est manquant ou autoSplashscreen n'est pas activé.
• Si la mise à jour modifie l'état de l'app ou l'interface, l'utilisateur peut subir un changement perturbateur en pleine session.
• La position de l'utilisateur dans l'app peut être perdue si keepUrlPathAfterReload n'est pas définie, ce qui pourrait le désorienter.
• Vous devrez gérer soigneusement la sauvegarde et la restauration de l'état pour garantir une transition fluide.

Si vous activez l'application instantanée, nous recommandons :

• D'envoyer avec npx @capgo/cli@latest bundle upload --delta pour que le téléchargement ne ralentisse pas l'expérience utilisateur.
• D'installer @capacitor/splash-screen et le paramétrage autoSplashscreen: true par launchAutoHide: false.
• Paramètre keepUrlPathAfterReload vers true pour préserver la position de l'utilisateur dans l'app.
• Saving and restoring the app state as needed to avoid losing user progress.
• Tester minutieusement le comportement des mises à jour de votre app pour éviter les transitions brusques, la perte d'état ou les changements de position déroutants.

Dans la plupart des cas, le comportement de mise à jour par défaut offre le meilleur équilibre entre la rapidité de livraison et la minimisation des interruptions. Mais pour les apps ayant des besoins spécifiques, Capgo offre la flexibilité nécessaire pour personnaliser quand et comment les mises à jour sont appliquées.

Continuer la lecture : Comportement des mises à jour

Si vous utilisez Comportement de mise à jour pour planifier la livraison de live update, connectez-l’à Capgo Live Updates pour le workflow produit dans Capgo Live Updates, Aperçu pour les détails d'implémentation dans Vue d'ensemble, Fonctionnalités pour le détail d’implémentation dans Fonctionnalités, Types de mise à jour pour les détails d'implémentation dans Update Types, et Prise en main pour les détails d'implémentation dans Getting Started.