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 perturber 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 trouver un équilibre entre la livraison rapide des mises à jour et la minimisation des perturbations 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 repasse 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 à intervalle régulier, contrôlée 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 passe l’application en arrière-plan.

4. Lorsque l’utilisateur ramène l’application au premier plan, il utilisera la version mise à jour.

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

Astuce

Capgo vérifie les mises à jour à chaque passage de l’app au premier plan et à intervalle régulier tant que l’app 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 ni forcés d’attendre un téléchargement en pleine session.

• Les mises à jour sont appliquées de manière transparente entre deux sessions, garantissant une expérience de lancement toujours fraîche.

• Vous pouvez livrer des mises à jour fréquemment sans craindre de perturber les utilisateurs actifs.

Le principal inconvénient est que si un utilisateur passe l’app en arrière-plan puis la reprend rapidement, il peut perdre l’état non enregistré, la mise à jour ayant été appliquée entre ces deux actions.

Pour atténuer ce risque, nous recommandons :

• Enregistrer l’état fréquemment et le restaurer proprement à la reprise de l’app.

• Éviter les mises à jour très fréquentes qui modifient une grande partie 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 config 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 capacitor.config.ts fichier, et non dans JavaScript code. Il prend en charge 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 au prochain passage en arrière-plan
• 'atInstall': N'appliquer immédiatement qu'après une installation propre ou une mise à jour native depuis le store ; 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 garde-fous de configuration de la version native, de la politique de canal et de l’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") require 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 les appReady é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.

Utiliser le mode d’application instantanée peut être utile pour livrer des correctifs critiques ou des correctifs de sécurité, mais cela implique certains compromis :

• L’utilisateur peut voir un bref clignotement ou un état de chargement pendant 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’application ou l’interface, l’utilisateur peut voir un changement perturbant en pleine session.
• La position de l’utilisateur dans l’application peut être perdue si keepUrlPathAfterReload n’est pas défini, ce qui peut le désorienter.
• Vous devrez gérer soigneusement la sauvegarde et la restauration de l’état pour assurer une transition fluide.

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

• Envoyer avec npx @capgo/cli@latest bundle upload --delta afin que le téléchargement ne ralentisse pas l’expérience utilisateur.
• Installation @capacitor/splash-screen et configuration autoSplashscreen: true par launchAutoHide: false.
• Paramètre keepUrlPathAfterReload vers true pour conserver la position de l’utilisateur dans l’application.
• Enregistrer et restaurer l’état de l’application au besoin pour éviter de perdre les progrès de l’utilisateur.
• Tester rigoureusement le comportement de mise à jour de votre application pour éviter les transitions brutales, 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 compromis entre livrer rapidement les mises à jour et minimiser les interruptions. Mais pour les applications qui ont des besoins spécifiques, Capgo permet de personnaliser quand et comment les mises à jour sont appliquées.

Continuer depuis Comportement de mise à jour

Si vous utilisez Comportement de mise à jour pour planifier la livraison de live update, connectez-l’à Live Updates Capgo 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 Types de mise à jour, et Prise en main pour les détails d'implémentation dans Getting Started.