Mettre à jour correctement les applications CapacitorJS

Vous découvrez une regression de paiement sur un vendredi après-midi. La correction est déjà dans votre layer web Capacitor, mais la fenêtre de révision de l'App Store ne se refermera pas pendant trois jours. Les utilisateurs Android peuvent recevoir un nouveau paquet plus tôt, mais forcer chaque client à réinstaller une mise à niveau native pour une correction JavaScript uniquement est toujours inutile.

C'est la raison pratique pour laquelle les équipes apprennent à mettre à jour OTA les applications CapacitorJS. Une mise à jour contrôlée en ligne peut livrer un bundle web signé aux binaires installés éligibles, le télécharger en arrière-plan et l'appliquer à la prochaine mise en route, tandis que les modifications natives suivent toujours le processus de l'App Store. La partie difficile n'est pas de télécharger un fichier. C'est de garder la cible de version, la signature, le contrôle de lancement, l'observabilité et la récupération alignés sur une flotte en ligne.

Table des Matières

• Why OTA Matters for CapacitorJS Teams
  • Traitez l'actualiseur comme une pipeline de livraison
• Prérequis et installation de l'actualiseur Capgo
  • Vérifiez avant de construire une mise à jour
• Expédiez votre premier bundle OTA de manière sécurisée
  • Lisez le tableau de bord comme une porte de version
• Canaux, lancements et automatisation CI/CD
  • Connectez la promotion à l'automatisation CI
• Stratégies de test et mise à jour automatique
  • Contrôler séparément le serveur et la récupération du client
• Signature, sécurité et ce que l'OTA ne peut pas changer
  • Définir les limites dans le plan de lancement
• Liste de vérification opérationnelle avant chaque lancement
  • Avant l'envoi
  • Pendant la promotion

Why OTA Matters for CapacitorJS Teams

Une application Capacitor contient généralement deux surfaces de mise à jour. Le code natif porte la coquille de la plateforme, les permissions, les plugins, les icônes, les droits et autres capacités examinées par les magasins. La couche web porte le JavaScript, le CSS, l'HTML, la navigation, le texte et les assets. Les mises à jour OTA s'attaquent à la deuxième surface, permettant ainsi à une équipe de corriger un flux de vérification brisé sans recompiler la coquille native, à condition que le changement reste dans les limites de la plateforme et des politiques des magasins décrites dans les Capgo lignes directrices OTA.

Le bénéfice opérationnel est plus que la vitesse. Les binaires installés ne bougent pas en même temps. Certains clients lancent une version native plus ancienne, d'autres utilisent une version récente du magasin, et chaque binaire peut avoir des API natives différentes disponibles pour le bundle web. Un bundle compilé contre une version native non prise en charge API peut échouer même si la différence de JavaScript est valide. Cela fait de l'OTA un système de compatibilité, et non un raccourci autour de l'ingénierie de lancement.

Traitez l'actualiseur comme une chaîne de livraison

Une mise en production nécessite une séquence claire :

1. Installez le pont natif : Ajoutez le package d'actualisation et synchronisez Capacitor afin que iOS et Android en soient informés.
2. Signez le bundle : Conservez les matériaux de signature à l'extérieur du dépôt et intégrez la vérification dans le chemin du client.
3. Ciblez un canal : Routez les cohortes de staging, bêta, production ou spécifiques aux clients avec intention.
4. Automatisez la livraison : Let CI build, sign, upload, and promote only after tests pass.
5. Observez l'adoption : Suivez les signaux de téléchargement, d'installation, de démarrage, de panne et de santé par canal et par binaire.
6. Revenir rapidement : Restaurer un bundle connu-good côté serveur et conserver la protection de récupération côté client.

Capgo est une option pour ce workflow. Son Capacitor mise à jour open-source et son service cloud publient des bundles web signés vers des canaux ciblés, les appliquent à la prochaine mise en route et exposent des informations de version et de niveau de dispositif de livraison. Disponibilité de l'application pour les applications Capacitor.

Règle pratique : Si vous ne pouvez pas identifier quel binôme natif un bundle cible, n'envoyez pas ce bundle en production.

OTA réussit lorsque cela réduit les mises en magasin inutiles sans cacher la frontière entre le web code et le binôme natif code. La question n'est pas de savoir si votre équipe peut pousser un bundle. C'est de savoir si vous pouvez expliquer qui a reçu le bundle, pourquoi ils étaient éligibles, ce qui s'est passé après la mise en route et comment vous restaurerez le service lorsque le bundle se comportera mal.

Prérequis et installation de la mise à jour Capgo

Avant d'ouvrir une invite de commande, assurez-vous que les comptes de projet et de version sont prêts. Vous aurez besoin d'une application Capacitor 5 ou 6. @capacitor/cli une Node 18 ou plus récente, des comptes Apple Developer et Google Play Console actifs pour les binaires ciblés, et un compte Capgo cloud avec un appId et une clé API.

La première installation est intentionnellement petite :

npm install @capgo/capacitor-updater
npx cap sync
npx @capgo/cli init

npm install ajoute le package JavaScript et la dépendance native. npx cap sync est l'étape que les gens ignorent, et cette omission laisse le pont natif non lié. La couche JavaScript peut compiler tandis que le runtime appelle ultérieurement un pont qui n'est pas présent dans le fichier binaire installé. Effectuez une synchronisation après l'installation et à nouveau lorsque les paramètres de configuration du plugin natif changent.

Le patcheur modifie votre capacitor.config.ts avec les paramètres de mise à jour, l'endpoint web et le canal par défaut. N'acceptez pas le patch aveuglément. Ouvrez le fichier et vérifiez explicitement l'identité de l'application et le contrat de mise à jour :

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example',
  version: '1.0.0',
  autoUpdate: true,
  updateUrl: '',
  capgo: {
    channel: 'staging'
  }
}

La structure générée exacte peut varier en fonction de votre projet et de la version CLI, mais les valeurs importantes sont les mêmes. appId doit correspondre au fichier binaire installé. version doit décrire la relation de construction native. autoUpdate doit refléter votre politique de lancement. updateUrl doit pointer vers le service que votre fichier binaire confie, et le capgo block doit identifier le canal initial.

Vérifiez avant de construire une version de production

Exécutez la commande de diagnostic avant d'ouvrir Xcode ou Android Studio :

npx @capgo/cli doctor

Afin que le résultat soit propre, il devrait confirmer que le CLI est disponible, que la configuration du projet est lisible, que le package de mise à jour est détecté, que les identifiants d'application requis existent et que l'authentification peut atteindre le compte configuré. Il ne devrait pas signaler une synchronisation native manquante, une identité d'application absente ou une configuration de mise à jour non valide.

Maintenez la première mise en production native délibérément ennuyeuse. Installez-la sur un appareil iOS physique et un appareil Android, lancez-l’avec accès réseau, fermez-l’et rouvrez-la, et confirmez que la mise à jour peut vérifier sans affecter le chemin d'initialisation normal. Le flux de mise à jour d'installation de l'Capacitor est utile lorsque vous devez comparer la configuration du projet avec la mise en place attendue du plugin.

Expédier votre premier bundle OTA de manière sûre

Traitez la première mise à jour comme un test de chemin de livraison, et non comme un lancement de fonctionnalité. Créez ou faites tourner la clé de signature avant de préparer l'artefact :

npx @capgo/cli key create

Placez la clé privée dans un gestionnaire de secrets. N'y commitez pas, n'y stockez pas dans un archive de projet ou n'y exposez pas dans la sortie de CI. Le chemin de confiance native nécessite le matériel de vérification public. Seule la tâche de signature devrait accéder à la clé privée.

Modifiez la version côté JavaScript dans package.json ou vos métadonnées de publication web. Gardez les champs de version native inchangés pour une correction web uniquement. Un bundle OTA ne peut ajouter une version native code ou modifier les capacités déclarées par le binôme installé, donc une modification de version native obscurcirait la compatibilité plutôt que de l'améliorer.

Téléchargez l'artefact signé vers le canal prévu :

npx @capgo/cli bundle upload --channel production

Une mise en ligne réussie ne confirme que le serveur a accepté une requête. Lisez la sortie de la commande et vérifiez l'identifiant de la charge utile, la contrainte de version native cible, le checksum signé et l'affectation de la chaîne.

Lisez le tableau de bord comme une porte de version

La vue détaillée du bundle devrait résoudre quatre questions de mise à jour.

• Version native minimale : Quel binôme le plus ancien peut exécuter ce bundle ?
• Version native maximale : Quels binares plus récents sont intentionnellement exclus ?
• Chaîne : Quel public peut découvrir l'artefact ?
• Pourcentage de lancement : Combien de ce public éligible peut le recevoir ?

Démarrez l'exposition en production à 5%Vérifiez ensuite les preuves requises pour l'expansion. Vérifiez le téléchargement et l'installation réussis, les démarrages froids normaux, les sessions sans crash et les erreurs JavaScript dans le flux modifié. Gardez l'identité et les contrôles de livraison de l'artifact visibles ensemble dans le tableau de bord Capgo.

Use a debug build to exercise the device path. getCurrent() indique le bundle actif, et notifyAppReady() confirme que le nouveau bundle a atteint un état sain :

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

const current = await CapacitorUpdater.getCurrent()
console.log(current)

await CapacitorUpdater.notifyAppReady()

Appelez la disponibilité uniquement après que l'application ait initialisé suffisamment pour passer vos vérifications de santé. Si elle ne confirme jamais la disponibilité, la récupération automatique peut marquer le bundle échoué lors du prochain démarrage froid. Cette mesure de sécurité protège les utilisateurs en production, mais elle peut également faire apparaître un test incomplet comme un problème de livraison. Enregistrez le bundle actif et le résultat de démarrage pour chaque appareil de test avant de faire progresser l'exposition.

Canaux, Lancements, et Automatisation CI/CD

Les canaux sont la couche de routage entre un bundle publié et un appareil installé. Ils sont également votre porte de sortie. Un canal de mise en scène devrait pointer vers un binôme natif connu, un canal bêta devrait servir un groupe contrôlé, et la production devrait se déplacer uniquement après que le canal précédent ait passé les tests de fumée.

Créez un chemin de mise en scène avec des noms explicites :

npx @capgo/cli channel create staging
npx @capgo/cli bundle assign <bundle-id> --channel staging

Fixez ce canal à la version native utilisée par vos appareils de test. Les testeurs doivent exécuter la même version binaire que la production, et non une version de développement locale avec des plugins supplémentaires ou une configuration différente. Une fois que le smoke suite passe, promouvez l'artefact testé plutôt que d'uploader une deuxième version légèrement différente.

Votre carte de canaux doit vivre dans capgo.config.json et être examinée comme une application code. Gardez les noms de canaux stables, identifiez la plage de compatibilité native prévue et faites de la promotion de production une action CI explicite. Pour les équipes gérant l'exposition de fonctionnalités en parallèle de l'exposition de livraison, ces conseils de gouvernance des drapeaux de fonctionnalité offrent un moyen utile de séparer les permissions de déploiement des activations utilisateur.

Reliez la promotion à CI

A practical GitHub Actions design has two paths:

• Soumissions de code : Construire la couche web, signer avec un jeton de preview restreint et publier dans un canal de preview éphémère. Détruire ou expirer ce canal lorsque la soumission de code est fermée.
• Sorties de version principales étiquetées : Exécutez les tests unitaires, construisez le bundle de production, validez sa contrainte de version native, téléchargez-l’et promouvez-l’uniquement lorsque la tâche de test se termine avec succès.

Une commande de promotion peut ressembler à ceci :

npx @capgo/cli bundle promote <bundle-id> \
  --to-channel production \
  --percent 5

Augmentez l'exposition en étapes délibérées telles que 25%, 50% et 100%, avec une approbation CI ou un job surveillé entre chaque étape. Les pourcentages et les commandes sont des contrôles, pas des preuves de sécurité. Un build réussi vous indique que le bundle est syntaxiquement valide. Il ne vous dit pas comment il se comporte sur un binôme natif particulier, avec un état local persistant, une connexion lente ou un appareil qui reprend une session ancienne.

Limite de version : Un bundle web appartient à une fenêtre de compatibilité binaire. Un canal ne doit jamais devenir un trou de serrage pour servir code qui référencent des API natives que l'application installée ne contient pas.

Conservez les builds de TestFlight et Android internal-track cohérents en liant chaque bundle à la version native exacte pour laquelle il a été construit. Si la version native change, publiez un nouveau bundle ciblant la compatibilité ou créez une nouvelle carte de canal. Le Capgo GitHub Guide d'intégration des actions peut aider à traduire cette politique en étapes de flux de travail répétitives.

Stratégies de test et Retour automatique

Une mise à jour OTA peut passer par la CI et encore échouer après activation. L'échec peut dépendre du bundle, du binôme natif, de l'état de l'appareil stocké ou des conditions réseau. Un simulateur peut confirmer que l'écran s'affiche, mais il ne peut pas couvrir tous les binômes installés ou montrer si un démarrage échoué se rétablit proprement.

Utilisez trois niveaux de test :

1. Tests de CI bundle : Exécutez les tests unitaires, les vérifications de type, la mise en forme et une construction web de production. Exercez les chemins de paiement, d'authentification, de navigation et de persistance modifiés au lieu d'arrêter à la compilation.
2. Canal de dispositif privé : Semez un canal privé avec des appareils physiques exécutant la version native précédente. Abordez les deux plateformes, les installations propres, les mises à niveau et les états stockés représentatifs.
3. Canary de production : Commencez avec un petit groupe éligible, un rapport de crash connecté et des alertes d'erreurs JavaScript. Traitez les échecs de démarrage comme urgent car les utilisateurs affectés peuvent ne jamais atteindre le code qui signale une erreur en application.

Le Capacitor guide de test OTA explique les mécanismes de test. La règle opérationnelle est simple : testez chaque mise à jour contre la version native qu'elle est censée protéger.

Contrôle de serveur séparé de la récupération du client

Server-side rollback stops new downloads:

npx @capgo/cli channel set production --bundle <previous-id>

Cela change ce que les appareils éligibles découvrent ensuite. Cela ne supprime pas un bundle déjà téléchargé ou actif sur chaque appareil, donc le client a également besoin de contrôles de récupération. Configurez l'actualiseur pour conserver un fallback connu et revenir après une condition d'échec de démarrage définie.

Un chemin de récupération fiable comprend :

• Suivi des échecs de téléchargement : Distinguer les problèmes de connectivité des artefacts invalides.
• Suivi des échecs d'installation : Détection d'erreurs d'unpacking, de vérification et de système de fichiers.
• Suivi de la santé du démarrage : Confirmer que l'application atteint un état utilisable après activation.
• Redirection automatique : Restaurer le bundle précédent connu-good lors de démarrages répétitifs échoués.
• Escalade manuelle : Conserver les identifiants de l'appareil et du bundle pour le support et l'ingénierie.

À l'échelle de la flotte, un faible taux d'échec crée toujours une charge de support significative. Un taux d'actualisation OTA réussie de 99,95 % implique encore environ 1 000 échecs sur 1 million de dispositifs., according to OTA testing benchmarks for IoT fleets. La même source décrit des garde-fous incluant le rollback dans les 30 minutes, le taux d'erreur inférieur à 0,1 %, et 98 % des appareils à l'intérieur de la fenêtre prise en charge. Traitez ces exemples comme des exemples de benchmarks, et non comme des critères d'acceptation universels. Fixez le budget d'erreur en fonction du risque et de l'impact utilisateur de l'application.

Signature, Sécurité et ce que l'OTA ne peut pas changer.

Une mise à jour non signée fait de l'endpoint de livraison une partie de votre surface d'attaque de la chaîne d'approvisionnement. Le TLS protège la connexion, mais le client doit également confirmer que l'artefact téléchargé venait d'un processus de mise en production autorisé et n'avait pas été remplacé ou modifié en cours de transit.

Générez une paire de clés Ed25519 avec les outils de mise à jour. Stockez la clé privée dans un secret CI, et insérez la clé de vérification publique dans le code natif lors de la construction de l'application. Le client doit vérifier chaque bundle avant activation. Limitez les jetons CLI par environnement et par périmètre de permission, conservez les journaux d'upload et de promotion, et exigez une authentification forte pour les actions de production.

Traitez la rotation de clés comme une migration de compatibilité, et non comme une seule modification de configuration. Générez une clé de remplacement, expédiez une build native qui confie à la fois à la clé publique actuelle et à la clé publique de remplacement, puis signez les releases avec la nouvelle clé privée. Supprimez la clé ancienne uniquement après que les binaires natifs compatibles ont adopté la remplacement. En supprimant la confiance trop tôt, vous empêchez les anciens binaires d'accepter des mises à jour valides. Laisser une clé compromise confiée indéfiniment déjoue la rotation.

Tracez la limite dans le plan de release

OTA gère les changements de la couche web. Des releases natives sont nécessaires lorsque le changement dépend de capacités absentes du binaire installé :

Le Documentation de l'Capacitor mise à jour code-signant explains the verification model. Apply it operationally with tamper-evident audit logs, certificate verification, TLS, strict access controls, and an investigation process for version spoofing or key compromise.

La compatibilité ciblée reste importante car la population native installée change progressivement. 66% de tous les appareils actifs sur iOS 26 et 74% des appareils introduits dans les quatre dernières années sur iOS 26, tandis qu'un autre rapport plaçait iOS 26 à 79% de tous les appareils plus tard dans le cycle, comme résumé dans Recherche sur la gestion des clés OTA mobile. Ces chiffres couvrent différents points et populations d'appareils. La conclusion pratique est cohérente : même les plateformes matures ne mettent pas à jour tous les appareils en même temps. Attribuez des lots en fonction de la version native et des capacités, plutôt que de supposer qu'un artefact OTA unique convient à toute la flotte.

Liste de Contrôl’Opérationnel Avant Chaque Lancement

Conservez la liste de contrôle de lancement à une page, stockée avec le dépôt ou le livre de procédures. Mettez-l’à jour après chaque incident. Un contrôl’ajouté après une véritable défaillance empêche généralement la prochaine récurrence.

Avant l'envoi

• Confirmer la compatibilité : Vérifiez que le bundle cible la version native exacte et utilise aucune API de plugin indisponible.
• Vérifiez l'artifact : Construire à partir d'un espace de travail propre, inspectez les fichiers générés et confirmez la version web prévue.
• Protéger la signature : Confirmez que CI possède le secret et la clé attendus. Vérifiez que les journaux ne révèlent pas de matériel privé.
• Valider les canaux : Vérifiez les mappages de staging, de bêta et de production avant d'attribuer le bundle.
• Préserver la récupération : Enregistrez le bundle précédemment connu et vérifiez que le chemin de rechange fonctionne toujours.
• Exécuter des tests de fumée physiques : Vérifiez la prise en charge, la connexion, la navigation, la persistance et la mise à jour sur des appareils représentatifs.

Durant la promotion

Publiez d'abord à un groupe limité, puis observez les signaux liés à l'impact utilisateur :

• Sessions sans plantage : Comparez le résultat avec le précédent bundle et investigatez les régressions.
• Taux d'erreurs JavaScript : Grouppez les erreurs par bundle, version native, plateforme et chemin de fonctionnalité.
• Comportement de démarrage froid : Vérifiez si les modifications d'activation entraînent un démarrage du système ou affichent une page blanche.
• Couverture de fonctionnalité : Confirmez que la fonctionnalité activée à distance correspond au code binaire qu'elle reçoit.
• Adoption et échecs : Séparez les appareils éligibles qui n'ont pas vérifié une mise à jour des appareils qui ont vérifié et échoué.

Conservez la première fenêtre d'observation post-promotion pendant 30 minutes avant de faire une exposition accrue. Si un chemin critique est cassé, rétablissez le canal de production sur le bundle précédent, conservez les journaux et décidiez si la correction appartient à un autre bundle OTA ou à une nouvelle version native.

Discipline de livraison : Un bundle de rechange aide uniquement lorsque l'équipe connaît son identifiant, sa plage de compatibilité et sa commande de restauration.

Traitez ce checklist comme un opérateur partagé code. Capgo peut fournir la livraison de bundle signé, la ciblage de canal, le contrôle de déploiement, l'historique de mise à jour et l'observabilité au niveau du dispositif. Votre équipe possède toujours la politique de compatibilité et la décision de promotion.

Capgo donne aux équipes de CapacitorJS un chemin contrôlé pour les mises à jour de JavaScript, de CSS, de configuration et de ressources, avec des canaux, une livraison étalée, une protection de reversion et une observabilité de mise en production. Insérez le checklist dans la prochaine déploiement, le testez contre un binaire de staging et évaluez Capgo pour le flux de travail de production.