Comment mettre à jour correctement les applications CapacitorJS en OTA

You find a checkout regression on Friday afternoon. The fix is already in your Capacitor web layer, but the App Store review window won’t close for three days. Android users can receive a new package sooner, yet forcing every customer to reinstall a native build for a JavaScript-only correction is still wasteful.

Vous trouvez une regression de paiement sur l'après-midi de vendredi. La correction est déjà dans votre layer web __CAPGO_KEEP_0__, mais la fenêtre de revue 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 à jour native pour une correction JavaScript uniquement est toujours gaspilleur.

Table des matières

• Why OTA Matters for CapacitorJS Teams
  • Why Mise à jour OTA importe pour les équipes CapacitorJS
• Prérequis et installation de l'Capgo de mise à jour
  • Prérequis et installation de l'actualiseur __CAPGO_KEEP_0__
• Expédier votre premier bundle OTA de manière sécurisée
  • Lisez le tableau de bord comme une porte de version
• Canaux, déploiements, et automatisation CI/CD
  • Connecter la promotion à la CI
• Stratégies de test et annulation automatique
  • Séparer le contrôle du serveur de 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 version
• Vérifications opérationnelles avant chaque version
  • Avant l'envoi
  • Pendant la promotion

Why OTA Matters for CapacitorJS Teams

A une application Capacitor se trouvent généralement deux surfaces de mise à jour. Le code natif contient le shell de la plateforme, les permissions, les plugins, les icônes, les droits et autres capacités examinées par la boutique. La couche web contient JavaScript, CSS, HTML, routage, texte et ressources. Les mises à jour OTA s'attaquent à la deuxième surface, permettant ainsi à l'équipe de corriger un flux de paiement endommagé sans recompiler le shell natif, à condition que le changement reste dans les limites de la plateforme et des politiques de la boutique décrites dans les lignes directrices OTA de Capacitor Les lignes directrices OTA de Capgo.

Le bénéfice opérationnel est plus rapide que la vitesse. Les binaires installés ne bougent pas en parallèle. Certains clients lancent une version native plus ancienne, tandis que d'autres utilisent une version récente de la boutique, et chaque binaire peut avoir des API natives différentes disponibles pour le paquet web. Un paquet compilé contre une version API native non prise en charge 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 la mise en production.

Traitez l'actualiseur comme un pipeline de livraison

Un setup de 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 paquet : 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 des cohortes de staging, de beta, de production ou spécifiques à un client intentionnellement.
4. Automatisation de la livraison : Let CI build, sign, upload, and promote only after tests pass.
5. Observer 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. Annuler 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 les canaux ciblés, les appliquent à la prochaine mise en route et exposent les 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 lorsqu'elle réduit les mises en magasin inutiles sans cacher la frontière entre le web code et le natif code. La question n'est pas de savoir si votre équipe peut envoyer un bundle. C'est de savoir si vous pouvez expliquer qui l'a reçu, pourquoi ils étaient éligibles, ce qui s'est passé après la mise en route et comment vous allez restaurer le service lorsque le bundle se comporte 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 initialisée, Node 18 ou plus récent, des comptes Apple Developer et Google Play Console actifs pour les binaires ciblés, et un Capgo compte cloud avec une appId et une API clé.

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 bin installé. Effectuez une synchronisation après l'installation et à nouveau lorsque la configuration du plugin natif change.

Le patcheur corrige 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 l'identité de l'application et le contrat de mise à jour explicitement :

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 restent les mêmes. appId doit correspondre au fichier bin installé, version doit décrire la relation de construction native, autoUpdate doit refléter votre politique de lancement, updateUrl doit pointer vers le service dont votre binaire a confiance, et le capgo le bloc doit identifier le canal initial.

Vérifiez avant de construire une version

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

npx @capgo/cli doctor

Un résultat propre 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 doit pas signaler une synchronisation native manquante, une identité d'application absente, ou une configuration de mise à jour invalide.

Conservez la première construction native délibérément banale. Installez-la sur un appareil iOS physique et un appareil Android, lancez-l’avec l'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 Capacitor flux de mise à jour d'installation est utile lorsque vous devez comparer la configuration du projet avec la mise en œuvre attendue du plugin.

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

Traitez le premier bundle comme un test de chemin de version, 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. La voie de confiance native nécessite le matériel de vérification public. Seule la tâche de signature doit accéder à la clé privée.

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

Télécharger l'artifact signé vers le canal prévu :

npx @capgo/cli bundle upload --channel production

Un téléchargement réussi ne confirme que le serveur a accepté une requête. Lisez la sortie de la commande et vérifiez l'identifiant de bundle, la contrainte de version native cible, le hachage signé et l'affectation du canal. Ces champs identifient l'artifact et montrent si les binaires installés sont éligibles à le recevoir.

Lisez le tableau de bord comme une porte de version

La vue détaillée du bundle devrait résoudre quatre questions de version :

• Version native minimale : Quel binaire le plus ancien peut exécuter ce bundle ?
• Version native maximale : Quels binaires plus récents sont intentionnellement exclus ?
• Canal : Quel public peut découvrir l'artifact ?
• Pourcentage de déploiement : Combien de cette audience éligible peut la recevoir ?

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

Utilisez une build de débogage pour tester le chemin du périphérique. 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. Ce garantie protège les utilisateurs en production, mais elle peut également faire paraî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 d'étendre l'exposition.

Canaux, Lancements, et Automatisation CI/CD

Les canaux sont la couche de routage entre un artefact publié et un appareil installé. Ils sont également votre porte de sortie. Un canal de mise en scène devrait pointer vers un binaire 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 test de fumée passe, promouvez l'artifact testé plutôt que d'uploader une deuxième version légèrement différente.

Votre carte de canal doit vivre dans capgo.config.json et être examinée comme une application code. Gardez les noms de canal 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 de l'activation utilisateur.

Reliez la promotion à CI

Un design d'Actions pratique GitHub a deux chemins :

• Soumissions de code : Construire la couche web, signer avec un jeton de preview restreint, et publier dans un canal de prévisualisation é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, puis 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 publication : 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 TestFlight et Android internes 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 workflow 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 vérification de sortie, d'authentification, de navigation et de persistance au lieu d'arrêter à la compilation.
2. Canal de dispositif privé : Seedez un canal privé avec des appareils physiques exécutant le précédent binaire natif. Abordez les deux plateformes, les installations propres, les mises à niveau et les états stockés représentatifs.
3. Canary de production : Démarrez avec une petite cohorte éligible, des rapports de crash connectés et des alertes d'erreurs JavaScript. Traitez les échecs de démarrage comme des urgence car les utilisateurs affectés peuvent ne jamais atteindre le code qui signale une erreur en application.

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

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

Arrêt du serveur : arrêt des téléchargements nouveaux :

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.

Ayant une voie de récupération fiable inclut :

• 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.
• Fallback automatique : Restaurer le bundle précédent connu-good lors de démarrage répétitif.
• Escalade manuelle : Conserver les identifiants de l'appareil et du bundle pour le support et l'ingénierie.

A 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 rend le point de terminaison de livraison 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'a 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 étendue de permission, conservez les journaux d'upload et de promotion, et exigez une forte authentification pour les actions de production.

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

Définissez la limite dans le plan de release

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

Le Capacitor mises à jour OTA code de signature documentation 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 ces 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 de 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. Assignez des lots en fonction de la version native et de la capacité, 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 run. Mettez à jour après chaque incident. Un contrôl’ajouté après une véritable faillite empêche généralement la prochaine récurrence.

Avant l'envoi

• Confirmer la compatibilité : Vérifiez que le bundle cible le binôme natif exact 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ériau 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 : Enregistrer le bundle précédemment connu et vérifier 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 crash : 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 plus large. Si un chemin critique se brise, rétablissez le canal de production sur le bundle précédent, préservez les journaux et décidiez si la correction appartient à un autre bundle OTA ou à une nouvelle mise à jour native.

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

Traitez ce checklist comme un opérationnel partagé code. Capgo peut fournir la livraison de bundle signé, la ciblage de canal, le contrôle de lancement, l'historique des mises à 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 biens, avec des canaux, une livraison étalée, une protection de retrait et une observabilité de la mise à jour. 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.