Comportement de mise à jour

Lorsque vous publiez une mise à jour de votre application Capgo, vous souhaitez probablement que vos utilisateurs reçoivent cette mise à jour le plus rapidement possible. Mais vous ne voulez pas non plus perturber leur expérience en leur imposant de attendre un téléchargement ou de redémarrer l'application au milieu d'une session.

Capgo’s comportement de mise à jour 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. Quand l'application passe en avant-plan, le plugin Capgo vérifie si une nouvelle mise à jour est disponible. Alors 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. Quand l'utilisateur ramène ensuite l'application en avant-plan, ils auront la version mise à jour.

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

Conseil

Capgo vérifie les mises à jour chaque fois que l'application passe en avant-plan et sur un horloge répétitif tout en restant ouverte. periodCheckDelay Contrôle cette intervalle (par défaut 10 minutes).

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 invites de mise à jour ou contraints de patienter pendant les téléchargements au milieu d'une session.

• Mises à jour sont appliquées de manière fluide entre les sessions, de sorte que l'expérience de lancement de l'application reste 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.

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

Personnalisation de l'application des mises à jour

Dans certains cas, vous pouvez vouloir 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 de l'application avec une modification côté serveur.

Capgo fournit une setDelay Fonction qui vous permet de spécifier des conditions qui doivent être remplies avant que l'update soit installé :

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 aurait été mis en arrière-plan pendant au moins 60 secondes.

Les conditions de retard disponibles sont :

• date: Attendre jusqu'après une date et 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 le code natif avec une version minimale soit installé 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 la mise à jour 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 version.

Mise à jour immédiate

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 un événement 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'envoi d'un zip complet ralentit l'expérience utilisateur.

Ces modes nécessitent également @capacitor/splash-screen and autoSplashscreen: true et SplashScreen.launchAutoHide: falseSans le plugin splash, l'utilisateur peut voir un éclairage ou une interface utilisateur décalée pendant l'application de la mise à jour.

avec autoUpdate est défini sur "atInstall", "onLaunch"Lorsque "always" dans votre capacitor.configDans les environnements non interactifs, le CLI détecte automatiquement les mises à jour Delta, tandis qu'il vous demande confirmation avant de procéder à l'upload dans les environnements interactifs. directUpdate config est toujours détecté. Utilisez --no-delta pour forcer un téléchargement de bundle complet.

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

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

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

Tester une Build Native Sans Mises à Jour en Direct

Voir Tester les Builds Native Sans Mises à Jour Pour la version native, la politique de canal et la configuration de 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: les modes d'application instantanée n'appliquent les mises à jour que lorsque le plugin les vérifie effectivement. Par défaut, les vérifications sont exécutées lorsque l'application passe en avant-plan et sur un horloge répétitive pendant que l'application reste ouverte. periodCheckDelay qui contrôle cet intervalle (par défaut 10 minutes).

Avec autoUpdate: 'always', Capgo effectue des vérifications à chaque transition en avant-plan et applique une mise à jour immédiate 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 pendant que l'application reste ouverte.

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

Attention

Modes d'application instantanés nécessitent @capacitor/splash-screen et autoSplashscreen: true. Définir launchAutoHide: false Dans la configuration de SplashScreen (comme montré 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 ensuite décider quand appeler CapacitorUpdater.set() Gestion automatique de l'écran de splash

Downloading Automatically Without Applying

Modes d'application instantanés ("atInstall", "onLaunch", "always") nécessitent autoSplashscreen et @capacitor/splash-screen (Disponible depuis la version 7.6.0). Installez le plugin, puis maintenez la splash visible jusqu'à ce que Capgo la cache :

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 cache automatiquement l'écran de chargement lors de l'application d'une mise à jour
• Le plugin cache automatiquement l'écran de chargement 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

Conservation autoSplashscreen: true. Si vous avez besoin de logique supplémentaire après que l'update soit prêt, écoutez appReady Ne pas sauter le plugin de splash. 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 l'application a terminé de s'initialiser et d'appliquer les mises à jour en attente.

Définir keepUrlPathAfterReload to 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.

Utiliser un mode d'application instantanée peut être utile pour délivrer des correctifs de bogues critiques ou des correctifs de sécurité, mais cela comporte certains compromis.

• 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 un changement disruptif 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 soigneusement 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 la configuration autoSplashscreen: true avec launchAutoHide: false.
• Configuration 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.
• Enregistrement et restauration de l'état de l'application au besoin pour éviter la perte de progression de l'utilisateur.

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 de comportement

Si vous utilisez Comportement de mise à jour pour planifier live update livraison, connectez-l’à Capgo Mises à jour en temps réel for the product workflow in Capgo Live Updates, Overview pour les détails d'implémentation dans Vue d'ensemble Features pour les détails d'implémentation dans les fonctionnalités, Mises à Jour pour les détails d'implémentation dans les types d'Update. pour les détails d'implémentation dans Types de mise à jour, et pour les détails d'implémentation dans Getting Started.