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 leur forçant à attendre un téléchargement ou à redémarrer l'application au milieu d'une 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 de la perturbation 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 en avant-plan, le plugin Capgo vérifie si une nouvelle mise à jour est disponible. Pendant que l'application reste ouverte, il vérifie à nouveau à intervalles réguliers contrôlés 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 tandis que l'utilisateur continue à 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. Lorsque l'utilisateur ramène l'application en avant-plan, ils seront en train de lancer la version mise à jour.

Ce flux garantit que les utilisateurs sont toujours en train de lancer la dernière version de votre application, sans jamais être interrompus par des invites de mise à jour ou contraints de attendre des téléchargements.

Conseil

Capgo vérifie les mises à jour chaque fois que l'application passe en avant-plan et à intervalles réguliers pendant que l'application reste ouverte. periodCheckDelay contrôle cette intervalle (10 minutes par défaut).

Pourquoi cette approche ?

Appliquer des mises à jour lors d'un événement de fond ou de kill présente quelques avantages clés pour l'expérience utilisateur :

• Les utilisateurs ne sont pas interrompus par des invitations de mise à jour ou contraints de attendre des téléchargements au milieu d'une session.

• Mises à jour appliquées de manière transparente entre les sessions, offrant ainsi une expérience d'ouverture de l'application toujours fraîche.

• Vous pouvez livrer des mises à jour fréquentes sans vous soucier de perturber les utilisateurs actifs.

Le principal inconvénient est que si un utilisateur met en arrière-plan et reprend rapidement votre application, il peut perdre tout l'état non enregistré depuis que la mise à jour a été appliquée entre ces actions.

Pour atténuer cela, nous recommandons :

• Enregistrer l'état fréquemment et le restaurer de manière gracieuse lorsque l'application reprend.

• Éviter des mises à jour très fréquentes qui modifient de grandes parties de l'état de l'application.

• Pensez à personnaliser le comportement de mise à jour pour les flux sensibles (voir ci-dessous).

Personnaliser quand les mises à jour sont appliquées

In certains cas, vous souhaitez peut-être avoir plus de contrôle sur l'exact moment où une mise à jour est appliquée. Par exemple, vous pourriez vouloir vous assurer que l'utilisateur a terminé un flux en cours avant de mettre à jour, ou coordonner une mise à jour d'une application avec une modification côté serveur.

Capgo fournit un setDelay Fonction qui vous permet de spécifier des conditions qui doivent être remplies 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'après le 1er juin 2023 ET l'application a été mis en arrière-plan pendant au moins 60 secondes.

Les conditions de retard disponibles sont :

• date: Attendre jusqu'à après une date/heure spécifique pour appliquer la mise à jour.
• backgroundAttendez une durée minimale après avoir mis l'application en arrière-plan pour appliquer la mise à jour.
• nativeVersion: Attendre que soit installé un code natif avec une version minimale avant d'appliquer la mise à jour.
• killAttendez la prochaine éviction de l'application pour appliquer la mise à jour.

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

Danger

Notez que la kill condition actuellement déclenche l'actualisation après le premier événement de mort, et non l'événement de fond suivant comme les autres conditions. Cette incohérence sera corrigée dans une prochaine mise à jour.

Appliquer les Mises à Jour Immédiatement

Pour les mises à jour critiques ou les applications avec un état très simple, vous pouvez vouloir appliquer une mise à jour dès qu'elle est téléchargée, sans attendre un événement de fond ou de mort. Capgo prend en charge cela via la autoUpdate politique dans votre Capacitor config.

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

"atInstall", "onLaunch", et "always" appliquer la mise à jour pendant que l'utilisateur attend. Utilisez Mises à Jour Delta seuls les fichiers modifiés téléchargent. L'upload d'un zip complet ralentit l'expérience utilisateur.

Ces modes nécessitent également @capacitor/splash-screen et autoSplashscreen: true avec SplashScreen.launchAutoHide: false. Sans le plugin de splash, l'utilisateur peut voir un éclat ou une interface utilisateur obsolète pendant l'application de l'update.

Lorsque 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 des mises à jour Delta automatiquement, et dans les environnements interactifs, il vous invite à confirmer avant de télécharger. directUpdate config est toujours détecté. Utilisez --no-delta pour forcer un upload de bundle complet.

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

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

• false ou 'off': Disable automatic update checks
• true ou 'atBackground' Vérifiez et téléchargez automatiquement à chaque vérification de premier plan, puis appliquez la mise à jour la prochaine fois que l'application passe en arrière-plan.
• 'atInstall': Appliquez immédiatement uniquement après une installation fraîche ou une mise à jour de l'application native ; sinon utilisez "atBackground" behavior
• 'onLaunch'comportement : Appliquer immédiatement uniquement lorsque l'application est ramenée en avant-plan à partir d'un état tué (démarrage froid). Après la première vérification, revenir à "atBackground" behavior
• 'always'Vérifiez à chaque transition en avant-plan et appliquez immédiatement dès que des mises à jour sont disponibles.
• 'onlyDownload': Vérifiez et téléchargez automatiquement, émettez updateAvailable, et n'installez jamais le prochain bundle ou appliquez une mise à jour automatiquement

Testez une Build Native Sans Mises à Jour en Ligne

Voir Testez les Builds Native Sans Mises à Jour pour la version native, la politique de canal et la sécurité de la configuration 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;

Note

Important: modes de mise à jour instantanée n'appliquent les mises à jour que lorsque le plugin effectue effectivement des vérifications. Par défaut, les vérifications s'exécutent lorsque l'application passe en avant-plan et sur un horloge répétitive tout en restant ouverte. periodCheckDelay contrôle cette intervalle (par défaut 10 minutes).

Avec autoUpdate: 'always', Capgo effectue des vérifications à chaque transition en avant-plan et applique immédiatement une mise à jour dès que le téléchargement est terminé pendant cette vérification, même si l'utilisateur utilise actuellement l'application. Les vérifications périodiques contrôlées par periodCheckDelay peuvent déclencher le même comportement d'application immédiate tout en restant ouverte.

Notez que puisque autoUpdate C'est une configuration native, les modes d'application instantanée nécessitent une gestion supplémentaire dans votre JavaScript code.

Attention

Instant apply modes nécessitent @capacitor/splash-screen et autoSplashscreen: true. launchAutoHide: false Dans la configuration de SplashScreen (comme illustré ci-dessus), la page d'accueil reste visible jusqu'à la fin de la mise à jour.

Téléchargement automatique sans application

Si vous souhaitez que Capgo vérifie et télécharge les mises à jour automatiquement mais ne les applique jamais 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 alors décider quand appeler CapacitorUpdater.set() ou afficher son propre prompt de mise à jour.

Gestion automatique de l'écran de splash

Les modes d'application instantanée ("atInstall", "onLaunch", "always"') nécessitent autoSplashscreen And @capacitor/splash-screen (Disponible depuis la version 7.6.0). Installez le plugin, puis maintenez la splash visible jusqu'à ce que Capgo la masque.

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

Lorsque autoSplashscreen est activé :

• Le plugin masque automatiquement l'écran de démarrage lorsqu'une mise à jour est appliquée
• Le plugin masque automatiquement l'écran de démarrage lorsqu'aucune mise à jour n'est nécessaire
• Vous n'avez pas besoin de vous tenir informé des appReady événements ou d'appeler SplashScreen.hide()

Extra work after the splash hides

Maintenez autoSplashscreen: true. Si vous avez besoin de logique supplémentaire après que l'update soit prêt, écoutez pour appReady de même. N'oubliez pas le plugin de splash ou autoSplashscreen pour cela :

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

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

CapacitorUpdater.notifyAppReady();

The appReady L'événement se déclenche une fois l'application a terminé d'initialiser et d'appliquer les mises à jour en attente.

Set keepUrlPathAfterReload à true Lorsque vous utilisez un mode d'application instantanée. Cela conserve l'actuelle chemin d'URL lorsque l'application est rechargée en raison d'une mise à jour.

lors de l'utilisation d'un mode d'application instantané. Cela préserve l'adresse URL actuelle lors du rechargement de l'application en raison d'une mise à jour.

• L’utilisateur peut voir un bref éclat 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 utilisateur, l'utilisateur peut voir une modification perturbatrice au milieu d'une session.
• The user’s location in the app may be lost if keepUrlPathAfterReload n'est pas défini, ce qui peut les dérouter.
• Vous devrez gérer avec soin la sauvegarde et la restauration de l'état pour assurer une transition fluide.

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

• Télécharger avec npx @capgo/cli@latest bundle upload --delta afin que le téléchargement ne ralentisse pas l'expérience utilisateur.
• Installer @capacitor/splash-screen et définir autoSplashscreen: true avec launchAutoHide: false.
• Définir keepUrlPathAfterReload à true conserver la position de l'utilisateur dans l'application.
• Sauvegarder et restaurer l'état de l'application au besoin pour éviter la perte de progression utilisateur.
• Testez soigneusement le comportement de mise à jour de votre application pour vous assurer qu'il n'y a pas de transitions brusques, d'état perdu ou de changements d'emplacement déstabilisants.

In most cases, the default update behavior provides the best balance of delivering updates quickly and minimizing disruption. But for apps with specific needs, Capgo provides the flexibility to customize when and how updates are applied.

Continuez de la mise à jour du comportement

Si vous utilisez Mise à jour du comportement pour planifier la livraison live update, connectez-l’à Capgo Live Updates for the product workflow in Capgo Live Updates, Résumé pour les détails d'implémentation dans Vue d'ensemble. Fonctionnalités pour les détails d'implémentation dans les fonctionnalités, Types d'actualisation pour les détails d'implémentation dans les types d'actualisation. Getting Started pour les détails d'implémentation dans Getting Started.