Comment bien gérer les mises à jour OTA pour les apps CapacitorJS

Vous découvrez une régression au checkout un vendredi après-midi. Le correctif est déjà dans votre couche web Capacitor, mais la fenêtre de review de l'App Store ne se refermera pas avant trois jours. Les utilisateurs Android peuvent recevoir un nouveau package plus tôt, mais forcer chaque client à réinstaller un build natif pour une correction purement JavaScript reste du gaspillage.

C'est la raison concrète pour laquelle les équipes apprennent à faire des mises à jour OTA sur CapacitorJS. Une release over-the-air maîtrisée peut livrer un bundle web signé aux binaires installés éligibles, le télécharger en arrière-plan et l'appliquer au prochain lancement, tandis que les changements natifs suivent toujours le processus des stores. La difficulté n'est pas d'envoyer un fichier, mais de garder le ciblage des versions, la signature, le contrôle du déploiement, l'observabilité et le rollback alignés sur un parc en production.

Table des matières

• Pourquoi l'OTA compte pour les équipes CapacitorJS
  • Considérez l'updater comme un pipeline de livraison
• Prérequis et installation de Capgo Updater
  • Vérifier avant de compiler une release
• Déployer votre premier bundle OTA en toute sécurité
  • Utiliser le dashboard comme garde-fou de release
• Canaux, déploiements progressifs et automatisation CI/CD
  • Connectez la promotion à la CI
• Stratégies de test et rollback automatique
  • Séparer le contrôle serveur de la récupération client
• Signature, sécurité et limites de l'OTA
  • Définir les limites dans le plan de release
• Checklist opérationnelle avant chaque release
  • Avant l'upload
  • Pendant la promotion

Pourquoi l'OTA compte pour les équipes CapacitorJS

Une application Capacitor comporte généralement deux surfaces de release. Le binaire natif contient le shell de la plateforme, les autorisations, les plugins, les icônes, les entitlements et d'autres fonctionnalités soumises à la revue du store. La couche web contient le JavaScript, le CSS, le HTML, le routage, les textes et les assets. Les mises à jour OTA ciblent la seconde surface, ce qui permet à une équipe de corriger un tunnel de paiement défaillant sans recompiler le shell natif, à condition que la modification reste dans les limites de la plateforme et de la politique du store décrites dans le Guide OTA Capgo.

L'avantage opérationnel va au-delà de la vitesse. Les binaires installés n'évoluent pas au même rythme. Certains clients lancent un build natif plus ancien, d'autres utilisent une version récente du store, et chaque binaire peut exposer des API natives différentes au bundle web. Un bundle compilé contre un API natif non pris en charge peut échouer, même si le diff JavaScript est valide. Cela fait de l'OTA un système de compatibilité, et non un raccourci par rapport à l'ingénierie de release.

Considérez l'updater comme un pipeline de livraison

Une configuration de production nécessite une séquence claire :

1. Installer le pont natif : Ajouter le package updater et synchroniser Capacitor pour qu'iOS et Android le prennent en compte.
2. Signer le bundle : Gardez les éléments de signature hors du dépôt et intégrez la vérification au chemin du client.
3. Cibler un canal : Routez délibérément les cohortes staging, beta, production ou spécifiques à un client.
4. Automatisez la livraison : Laissez la CI compiler, signer, envoyer et promouvoir uniquement après la réussite des tests.
5. Observez l'adoption : Suivez les signaux de téléchargement, d'installation, de boot, de crash et de santé par canal et par binaire.
6. Effectuez un rollback rapidement : Restaurez un bundle validé côté serveur tout en conservant la protection de récupération côté client.

Capgo est une option pour ce workflow. Son updater open source Capacitor et son service cloud publient des bundles web signés vers des canaux ciblés, les appliquent au prochain lancement et exposent les informations de livraison par version et par appareil. Les équipes qui évaluent la disponibilité et la résilience des releases peuvent aussi consulter la disponibilité des applications Capacitor.

Règle pratique : Si vous ne pouvez pas identifier quel binaire natif un bundle cible, ne promouvez pas ce bundle en production.

L'OTA réussit quand elle réduit les releases inutiles sur les stores sans masquer la limite entre le web code et le 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 l'a reçu, pourquoi il était éligible, ce qui s'est passé après le lancement, et comment vous rétablirez le service si le bundle se comporte mal.

Prérequis et installation de Capgo Updater

Avant d'ouvrir un terminal, vérifiez que les comptes du projet et de release sont prêts. Il vous faut une application Capacitor 5 ou 6 avec @capacitor/cli initialisée, Node 18 ou supérieur, des comptes Apple Developer et Google Play Console actifs pour les binaires cibles, et un compte cloud Capgo avec un appId et une clé API.

La première installation est volontairement minimale :

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 beaucoup sautent, et cet oubli laisse le bridge natif non lié. La couche JavaScript peut compiler alors que le runtime appellera ensuite un bridge absent du binaire installé. Lancez la synchronisation après l'installation, puis à chaque changement de configuration d'un plugin natif.

L'initialiseur patche votre capacitor.config.ts avec les paramètres de l'updater, 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 exacte générée peut varier selon votre projet et la version de CLI, mais les valeurs importantes restent les mêmes. appId doit correspondre au binaire installé, version doit décrire la relation avec le build natif, autoUpdate doit refléter votre politique de lancement, updateUrl doit pointer vers le service auquel votre binaire fait confiance, et le capgo bloc doit identifier le canal initial.

Vérifier avant de compiler une release

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

npx @capgo/cli doctor

Un résultat propre doit confirmer que le CLI est disponible, que la configuration du projet est lisible, que le package de l'updater est détecté, que les identifiants d'application requis existent et que l'authentification peut atteindre le compte configuré. Il ne doit pas signaler de sync native manquante, d'identité d'application absente ni de configuration d'updater invalide.

Gardez le premier build natif volontairement basique. Installez-le sur un appareil iOS et un appareil Android physiques, lancez-l’avec un accès réseau, fermez-le puis rouvrez-le, et confirmez que l'updater peut effectuer sa vérification sans affecter le démarrage normal. Le Workflow d'installation de l'updater Capacitor est utile lorsque vous devez comparer la configuration du projet avec la configuration attendue du plugin.

Déployer votre premier bundle OTA en toute sécurité

Considérez le premier bundle comme un test du chemin de release, et non comme le lancement d’une fonctionnalité. Créez ou faites pivoter 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. Ne la commitez pas, ne la stockez pas dans une archive de projet et ne l'exposez pas dans la sortie de la CI. Le chemin de confiance natif a besoin des éléments publics de vérification. Seul le job de signature doit accéder à la clé privée.

Modifiez la version côté JavaScript dans package.json ou dans les métadonnées de votre release web. Conservez les champs de version native inchangés pour un correctif web uniquement. Un bundle OTA ne peut pas ajouter de code natif ni modifier les capacités déclarées par le binaire installé ; un changement de version native masquerait la compatibilité au lieu de l'améliorer.

Envoyez l'artefact signé vers le canal cible :

npx @capgo/cli bundle upload --channel production

Un upload réussi confirme seulement que le serveur a accepté la requête. Lisez la sortie de la commande et vérifiez l'identifiant du bundle, la contrainte de version native cible, le checksum signé et l'attribution du canal. Ces champs identifient l'artefact et indiquent si les binaires installés sont éligibles pour le recevoir.

Utiliser le dashboard comme garde-fou de release

La vue détaillée du bundle doit répondre à quatre questions sur la release :

• Version native minimale : Which oldest binary can run this bundle?
• Version native maximale : Quels binaires plus récents sont volontairement exclus ?
• Canal : Quel public peut découvrir l’artefact ?
• Pourcentage de déploiement : Quelle part de ce public éligible peut le recevoir ?

Démarrer 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 à froid 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 dashboard Capgo.

Utilisez un build de debug pour tester le parcours sur l’appareil. getCurrent() signale 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()

Déclarez la readiness uniquement après que l’app s’est initialisée assez pour passer vos health checks. Si elle ne confirme jamais la readiness, la récupération automatique peut marquer le bundle comme échoué lors du prochain cold start. Ce garde-fou protège les utilisateurs en production, mais il peut aussi donner l’impression qu’un test incomplet est un problème de livraison. Enregistrez le bundle actif et le résultat du démarrage pour chaque appareil de test avant d’élargir le déploiement.

Canaux, déploiements progressifs et automatisation CI/CD

Les canaux sont la couche de routage entre un bundle publié et un appareil installé. Ils font aussi office de verrou de release. Un canal de staging doit pointer vers un binaire natif connu, un canal bêta doit cibler une cohorte contrôlée, et la production ne doit avancer qu’après que le canal précédent a passé les smoke tests.

Créez un chemin de staging avec des noms explicites :

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

Verrouillez ce canal sur la version native utilisée par vos appareils de test. Les testeurs doivent exécuter le même binaire que celui que la production prendra en charge, et non un build de développement local avec des plugins en plus ou une configuration différente. Une fois la suite de smoke tests réussie, promouvez l’artefact testé plutôt que d’envoyer un second bundle légèrement différent.

Votre mapping de canaux doit se trouver dans capgo.config.json et être relu comme le code de l'application. Gardez des noms de canaux stables, identifiez la plage de compatibilité native visée, et faites de la promotion en production une action CI explicite. Pour les équipes qui gèrent l'exposition des fonctionnalités en parallèle de celle de la livraison, ces conseils de gouvernance des feature flags offrent un moyen utile de séparer les permissions de déploiement de l'activation côté utilisateur.

Connectez la promotion à la CI

Une conception pratique de GitHub Actions comporte deux chemins :

• Pull requests : Compilez la couche web, signez-l’avec un identifiant de preview restreint et publiez-la sur un canal de preview éphémère. Détruisez ou laissez expirer ce canal à la fermeture de la pull request.
• Releases taguées sur main : Exécutez les tests unitaires, compilez le bundle de production, validez la contrainte de version native, envoyez-le, puis déployez uniquement si le job 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 par étapes progressives, par exemple 25 %, 50 % et 100 %, avec une validation CI ou un job surveillé entre chaque étape. Les pourcentages et les commandes sont des contrôles, pas une preuve de sécurité. Un build réussi indique que le bundle est syntaxiquement valide. Il ne dit rien sur son comportement avec un binaire natif particulier, un état local persistant, une connexion lente ou un appareil qui reprend une ancienne session.

Limite de release : Un bundle web s’inscrit dans une fenêtre de compatibilité binaire. Un canal ne doit jamais devenir une échappatoire pour servir des code qui référencent des API natives absentes de l’application installée.

Gardez les builds TestFlight et Android internal-track cohérents en associant chaque bundle à la version native exacte pour laquelle il a été compilé. Si le build natif change, publiez un nouveau bundle ciblant la compatibilité ou créez une nouvelle correspondance de canal. Le Capgo GitHub Guide d'intégration Actions peut vous aider à transformer cette politique en étapes de workflow reproductibles.

Stratégies de test et rollback automatique

Une release OTA peut passer la CI et échouer malgré tout après activation. L'échec peut dépendre du bundle, du binaire natif, de l'état stocké sur l'appareil ou des conditions réseau. Un simulateur peut confirmer le rendu d'un écran, mais il ne peut pas couvrir chaque binaire installé ni indiquer si un démarrage échoué se rétablit proprement.

Utilisez trois niveaux de test :

1. Tests de bundle en CI : Exécutez les tests unitaires, le typage, le linting et un build web de production. Testez les parcours de paiement, d'authentification, de navigation et de persistance modifiés au lieu de vous arrêter à la compilation.
2. Canal d'appareils privés : Initialisez un canal privé avec des appareils physiques exécutant l'ancien build natif. Couvrez les deux plateformes, les installations propres, les mises à jour et les états de stockage représentatifs.
3. Canary de production : Commencez avec une petite cohorte éligible, un reporting de crash connecté et des alertes sur les erreurs JavaScript. Traitez les échecs au démarrage comme urgents, car les utilisateurs concernés peuvent ne jamais atteindre le code qui signale une erreur dans l'application.

Le Guide de test OTA Capacitor explique le fonctionnement des tests. La règle opérationnelle est simple : tester chaque mise à jour avec le binaire natif qu'elle est censée protéger.

Séparer le contrôle serveur de la récupération client

Server-side rollback stops new downloads:

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

Cela modifie ce que les appareils éligibles découvrent ensuite. Cela n'efface pas un bundle déjà téléchargé ou actif sur chaque appareil, le client a donc aussi besoin de contrôles de récupération. Configurez l'updater pour conserver un fallback known-good et revenir en arrière après une condition d'échec au démarrage définie.

Un chemin de récupération fiable comprend :

• Suivi des échecs de téléchargement : Distinguez les problèmes de connectivité des artefacts invalides.
• Suivi des échecs d'installation : Detect unpacking, verification, and filesystem issues.
• Suivi de l’état de démarrage : Vérifier que l’application atteint un état utilisable après activation.
• Repli automatique : Restaurer le dernier bundle connu bon si le démarrage échoue de manière répétée.
• Escalade manuelle : Conservez les identifiants d’appareil et de bundle pour le support et l’ingénierie.

À l’échelle d’une flotte, un faible taux d’échec génère déjà une charge de support importante. Un Un taux de réussite OTA de 99,95 % implique encore environ 1 000 échecs par million d’appareils, selon les Benchmarks de test OTA pour les flottes IoT. La même source décrit des garde-fous : rollback en moins de 30 minutes, taux de crash inférieur à 0,1 % et 98 % des appareils dans la fenêtre de support. Considérez ces valeurs comme des exemples de référence, pas comme des critères d’acceptation universels. Définissez le budget d’erreurs selon le risque et l’impact utilisateur de l’app.

Signature, sécurité et limites de l'OTA

Une mise à jour non signée fait du point de livraison une composante de votre surface d’attaque de la chaîne d’approvisionnement. TLS protège la connexion, mais le client doit aussi confirmer que l’artefact téléchargé provient d’un processus de release autorisé et n’a pas été remplacé ni altéré en transit.

Générez une paire de clés Ed25519 avec l’outillage de l’updater. Stockez la clé privée dans un secret CI et intégrez la clé publique de vérification dans le binaire natif lors du build de l’application. Le client doit vérifier chaque bundle avant activation. Limitez les tokens CLI par environnement et par périmètre de permissions, conservez les logs d’upload et de promotion, et exigez une authentification forte pour les actions de production.

Considérez la rotation des clés comme une migration de compatibilité, pas comme un simple changement de configuration. Générez une clé de remplacement, livrez un build natif qui fait confiance à la fois à la clé publique actuelle et à celle de remplacement, puis signez les releases avec la nouvelle clé privée. Ne supprimez l’ancienne clé qu’une fois que les binaires natifs compatibles ont adopté la clé de remplacement. Retirer la confiance trop tôt empêche les binaires plus anciens d’accepter des mises à jour valides. Laisser indéfiniment une clé compromise dans la liste de confiance annule l’intérêt de la rotation.

Définir les limites dans le plan de release

L’OTA gère les modifications de la couche web. Des releases natives sont nécessaires lorsqu’un changement dépend de capacités absentes du binaire installé :

Le documentation sur la signature Capacitor updater code explique le modèle de vérification. Appliquez-le concrètement avec des logs d'audit infalsifiables, la vérification des certificats, le TLS, des contrôles d'accès stricts et un processus d'enquête en cas d'usurpation de version ou de compromission de clé.

Le ciblage de compatibilité reste important, car le parc natif installé évolue progressivement. Apple a indiqué 66 % de tous les appareils actifs sous iOS 26 et 74 % des appareils sortis ces quatre dernières années sous iOS 26, tandis qu'un autre rapport situait iOS 26 à 79 % de tous les appareils plus tard dans le cycle, comme récapitulé dans Recherche sur la gestion des clés OTA pour mobile. Ces chiffres couvrent différents moments et populations d'appareils. La conclusion pratique est la même : même les plateformes matures ne mettent pas tous les appareils à jour en même temps. Assignez les bundles selon la version native et les capacités, plutôt que de supposer qu'un seul artefact OTA convient à toute la flotte.

Checklist opérationnelle avant chaque release

Limitez la checklist de release à une seule page, stockée avec le dépôt ou le runbook. Mettez-l’à jour après chaque incident. Un contrôl’ajouté après un échec réel évite généralement la prochaine récurrence.

Avant l'upload

• Confirmer la compatibilité : Vérifiez que le bundle cible le binaire natif exact et n'utilise aucune API de plugin indisponible.
• Vérifier l'artefact : Compilez depuis un espace de travail propre, inspectez les fichiers générés et confirmez la version web attendue.
• Protéger la signature : Confirmez que la CI dispose du secret et de la clé attendus. Vérifiez que les logs n'exposent pas de matériel privé.
• Valider les canaux : Revuez les mappings staging, beta et production avant d'assigner le bundle.
• Préserver la récupération : Enregistrez le dernier bundle connu bon et vérifiez que le chemin de repli fonctionne toujours.
• Exécuter des tests de fumée physiques : Testez le démarrage, la connexion, le paiement, la navigation, la persistance et la préparation à la mise à jour sur des appareils représentatifs.

Pendant la promotion

Déployez d'abord sur une cohorte limitée, puis surveillez les signaux liés à l'impact utilisateur :

• Sessions sans crash : Comparez le résultat avec le bundle précédent et analysez les régressions.
• Taux d'erreurs JavaScript : Groupez les erreurs par bundle, version native, plateforme et chemin de fonctionnalité.
• Comportement au démarrage à froid : Vérifiez si l'activation modifie le démarrage ou laisse les utilisateurs sur un écran blanc.
• Couverture des fonctionnalités : Confirmez que les fonctionnalités activées à distance correspondent au binaire qui les reçoit.
• Adoption et échecs : Distinguez les appareils éligibles qui n'ont pas vérifié de mise à jour de ceux qui ont vérifié et échoué.

Maintenez la première fenêtre d'observation après promotion pendant 30 minutes avant d'élargir l'exposition. Si un chemin critique casse, revenez à la version précédente du canal de production, conservez les logs et décidez si le correctif doit figurer dans un autre bundle OTA ou dans une nouvelle release native.

Discipline le jour du déploiement : Un bundle de secours n'est utile que si l'équipe connaît son identifiant, sa plage de compatibilité et la commande de restauration.

Considérez cette checklist comme un code opérationnel partagé. Capgo peut assurer la livraison de bundles signés, le ciblage par canal, le contrôle du déploiement progressif, l'historique des mises à jour et l'observabilité au niveau de l'appareil. Votre équipe reste responsable de la politique de compatibilité et de la décision de promouvoir.

Capgo offre aux équipes CapacitorJS un chemin contrôlé pour les mises à jour signées de JavaScript, de CSS, de configuration et d'assets, avec des canaux, un déploiement progressif, une protection contre le rollback et l'observabilité des releases. Intégrez cette checklist au prochain déploiement, testez-la sur un binaire de staging, et évaluez-la Capgo pour votre workflow de production.