Aller au contenu principal

Capgo version_build vs version_name : étapes de configuration

Découvrez comment fonctionnent version_build et version_name de Capgo, d'où vient chaque valeur et comment vérifier l'éligibilité OTA avant de publier un bundle.

Diagramme de la baseline d'une app native Capacitor et du bundle Capgo téléchargé.

Capgoles noms de version peuvent sembler contre-intuitifs au début : version_build est la baseline de l’app native, tandis que version_name suit le bundle sur l'appareil. Comprendre cette distinction vous permet de vérifier pourquoi un appareil recevra, ou non, une mise à jour OTA avant de la déployer.

Nous avons analysé les pages de dépannage de 5 plateformes de live update, dont la nôtre, et avons constaté que notre documentation répertorie 7 codes nommés de mismatch version_build, contre 5, 2, 2 et 0 pour les quatre autres. Plus de codes nommés signifie moins de devinettes quand un mismatch version_build apparaît.

Table des matières

  • Étape 1 : Localisez version_build et version_name dans Capgo
  • Étape 2 : Identifiez la version native de référence et le bundle téléchargé
  • Étape 3 : Vérifiez l'origine de la version de votre app native
  • Étape 4 : Définissez et vérifiez la version du bundle reçue par Capgo
  • Étape 5 : Testez l'éligibilité du canal avant de déployer une mise à jour
  • Étape 6 : Diagnostiquez les écarts de version et rendez vos releases reproductibles
  • FAQ
  • Conclusion

Étape 1 : Localisez version_build et version_name dans Capgo

Commencez par les considérer comme deux faits distincts concernant une même installation d’app. version_build indique à Capgo quelle version native de l’application est sur l’appareil. version_name indique à Capgo quel bundle JavaScript l’appareil a téléchargé. Ces deux éléments peuvent avoir des valeurs différentes, et c’est souvent attendu.

Dans le modèle de versions de Capgo, la version native est le point de référence pour l’éligibilité aux mises à jour. Capgo compare le bundle assigné à un canal avec cette base native. La version du bundle installé sur l’appareil aide à identifier sa code web actuelle, mais ne remplace pas la base native dans les règles de version du canal.

Recherchez l’appareil sur la page Devices de la console Capgo et notez les deux valeurs avant de dépanner. Comparez-les ensuite avec le bundle cible du canal. Les règles des canaux Capgo expliquent comment la version cible d’un canal est vérifiée par rapport à version_build.

Valeur Ce que cela représente Utilisez-le pour répondre à Source typique
version_build Base native de l’app envoyée à Capgo Cette app native peut-elle recevoir le bundle cible du canal ? Version de l’app native, ou une valeur de configuration Capacitor explicite
version_name Bundle JavaScript actuellement téléchargé Quelle version de bundle est installée actuellement ? Version du bundle résolue lors de l’upload
Canal cible Bundle assigné au canal de l’appareil Quelle version Capgo vérifie-t-il pour une mise à jour ? Canal actuellement assigné

Conservez les trois valeurs dans des colonnes distinctes dans une note de version ou un rapport de test. Si l’équipe écrit une « version d’app » générique, il est facile de comparer la mauvaise paire. Pour l’éligibilité, comparez le bundle cible avec version_build. Pour le code web installé, vérifiez version_name.

La nomenclature de Capgo peut sembler différente des conventions Android, où les équipes utilisent souvent « build » pour désigner un numéro de build incrémental. Ici, lisez le champ selon son rôle de Capgo, et non selon ce que le nom suggère. Cette petite habitude évite beaucoup de confusion lors des releases.

Étape 2 : Identifiez la version native de référence et le bundle téléchargé

Avant de modifier une valeur de version, identifiez quel code est natif et quel code est livré sous forme de bundle. L’application native est le binaire iOS ou Android installé. Le bundle contient les assets web qu’une application Capacitor peut recevoir via une mise à jour OTA.

Imaginez une application native livrée avec une version de base 1.2.3. A later web fix is uploaded as bundle 1.2.4. Capgo vérifie si le bundle cible du canal est autorisé pour la baseline native 1.2.3. S'il est éligible, l'appareil peut télécharger ce bundle. Après l'installation, version_name reflète le bundle désormais présent sur l'appareil. La baseline native reste liée au binaire installé.

Cette différence compte quand un utilisateur a un build App Store plus ancien mais un bundle web plus récent. Le bundle peut changer sans remplacer le binaire natif, mais une mise à jour OTA ne peut pas ajouter de code natif qui n'était pas inclus dans l'app. Si un changement nécessite un nouveau plugin ou un paramètre natif, prévoyez un Native Build plutôt que de traiter un upload de bundle comme un substitut.

Diagramme de la baseline d'une app native Capacitor et du bundle Capgo téléchargé.

Utilisez ce contrôle rapide lorsque les valeurs semblent désynchronisées :

  • Confirmez quel binaire natif est installé sur l'appareil de test.
  • Trouvez la valeur de version que Capgo reçoit comme baseline native.
  • Vérifiez la version du bundle assignée au canal de l'appareil.
  • Enregistrez la version du bundle installé séparément des deux.

Ne déduisez pas la baseline native à partir de package.json sauf si votre processus de build copie délibérément cette valeur dans la version native ou la configuration Capgo. La version d’un projet JavaScript et la version de l’application installée depuis le store peuvent diverger. La bonne source est celle que votre application envoie réellement à Capgo.

Une fois que vous pouvez identifier la version de référence et le bundle actuel, l’étape suivante consiste à retracer chaque valeur jusqu’à son fichier source. C’est là que les différences entre plateformes ont tendance à apparaître.

Étape 3 : Vérifiez l'origine de la version de votre app native

Pour une référence fiable version_build, trouvez la version native que votre application Capacitor signale. La documentation sur les versions de Capgo décrit les clés de source distinctes pour iOS et Android, puis utilise la valeur native résultante comme référence de comparaison OTA.

Sur iOS

Vérifier CFBundleShortVersionString dans l'onglet Info.plist. Dans la plupart des projets Xcode, cette clé est définie à $(MARKETING_VERSION), la valeur que vous modifiez réellement est donc la Marketing Version de la cible. Vérifiez la valeur dans l’app compilée, pas seulement dans un template ou un fichier que le build peut écraser.

Lorsqu’une équipe met à jour le projet Xcode sans modifier la valeur qui atteint l’app, la vue locale du projet peut sembler correcte alors que le binaire installé indique autre chose. Comparez la version dans l’app native générée avec la valeur attendue par votre processus de release.

Sur Android

Vérifier defaultConfig.versionName dans la configuration Gradle de l’app Android. Ce nom de version native sert à la comparaison OTA de Capgo. Ne le confondez pas avec un code de build Android ou une version de package JavaScript sans rapport. Pour cette vérification, la question importante est le nom de version que l’app native envoie.

Une politique de version commune peut aider les deux plateformes à rester alignées, mais ne partez pas du principe qu’elles partagent déjà une même source. iOS et Android peuvent avoir des fichiers, des étapes de build ou des calendriers de release distincts. Comparez leurs valeurs finales lors de la vérification de release, surtout si une plateforme a un calendrier de déploiement sur les stores différent.

Certaines apps définissent explicitement la version native dans capacitor.config.ts via la valeur de version de la configuration de l’updater. Le Capgo Semver Tester décrit cette baseline native comme une valeur pouvant provenir de la configuration ou des métadonnées de l’app native. Si votre application remplace les métadonnées natives, documentez ce choix pour que personne ne s’attende à ce que la version du store soit la source.

Pour chaque plateforme, notez le fichier source, la valeur résolue et le build qui la contient. Cela facilite le suivi d'une incohérence après une release, lorsque le dépôt peut déjà contenir une version plus récente que celle de l'application installée sur l'appareil d'un testeur.

Modifiez uniquement la source que votre build lit réellement. Éditer un fichier obsolète peut donner l'impression qu'une revue code est complète, alors que la version native empaquetée reste inchangée.

Étape 4 : Définissez et vérifiez la version du bundle reçue par Capgo

La version du bundle décrit la mise à jour JavaScript, pas le binaire natif installé. Capgo peut récupérer cette version depuis le version champ dans package.json lorsque vous ne fournissez pas de version de bundle explicite. L'option de CLI --bundle peut définir la version envoyée lors de l'upload.

Choisissez une seule approche et rendez-l’explicite dans votre processus de release. Si package.json c'est la source, incrémentez ce champ avant l'upload. Si la CI transmet une version de bundle via CLI, faites en sorte que le job affiche la version résolue dans ses logs de release. Un mélange silencieux des deux approches rend plus difficile de comprendre pourquoi le canal a reçu une valeur donnée.

Utilisez le versionnage sémantique sous la forme major.minor.patch habituelle, telle que 1.2.3. Les stratégies de canal de Capgo utilisent les segments de cette version pour décider si un bundle cible correspond à une base native. Un suffixe de pré-release comme -beta.1 peut aider à étiqueter des builds spécifiques à un canal, mais veillez à ce que la version reste analysable et cohérente entre vos outils de release.

Réfléchissez bien à l'incrémentation avant de publier :

  • Utilisez une incrémentation patch pour un correctif web compatible dans la même ligne de release.
  • Utilisez un changement mineur lorsque la modification relève d’une nouvelle ligne de fonctionnalités compatible.
  • Utilisez un changement majeur lorsque la limite de compatibilité change et que les anciens natifs code ne peuvent pas supporter le bundle.

Ces libellés sont une convention d’équipe, pas un moyen d’ajouter une capacité native via OTA. Un numéro de version ne peut pas prouver qu’un bundle est sûr pour une application native. Gardez les décisions de compatibilité réelles liées au code et aux dépendances dans le binaire.

Avant l’upload, comparez la version du package ou la valeur CLI avec la version affichée pour le bundle après l’upload. Inspectez également le canal qui le servira. Envoyer un bundle correctement nommé vers un canal non prévu peut toujours entraîner un mauvais résultat de test.

Les chaînes invalides ou incohérentes méritent une vérification, pas une supposition. Conservez une valeur de release connue et fonctionnelle, corrigez la source et testez la version résolue avant de la promouvoir.

Le Référence de la commande Capgo CLI est utile lorsque vous intégrez l’upload dans un script, car la version du bundle fait partie des entrées de la commande de release.

Étape 5 : Testez l'éligibilité du canal avant de déployer une mise à jour

L'éligibilité au canal est une comparaison, pas une supposition basée sur le bundle qui semble le plus récent. Capgo compare le bundle cible du canal à la référence native envoyée comme version_build. Le bundle actuellement téléchargé, indiqué comme version_name, n'est pas la référence pour ces règles de canal.

Par exemple, supposons qu'une application native installée indique 1.2.3, alors que son bundle actuel est 1.2.4. Si un canal pointe vers 1.2.5, évaluez la cible par rapport à la référence native 1.2.3, et non simplement par rapport au bundle actuel 1.2.4. Les cibles autorisées dépendent de la stratégie de mise à jour du canal.

Capgo documente des stratégies comme « major » et « minor » qui restreignent les mises à jour par rapport à la référence native. Avec une stratégie « major », une cible avec une version majeure plus élevée peut être bloquée. Avec une stratégie « minor », une cible qui modifie la ligne majeure ou mineure de la référence peut être bloquée. Vérifiez la stratégie configurée plutôt que de supposer que chaque bundle qui semble plus récent sera accepté.

Un développeur teste l'éligibilité du canal Capgo pour un bundle OTA par rapport à une version de build natif.

Testez la combinaison exacte que vous prévoyez de publier :

  1. Installez le build natif correspondant aux utilisateurs visés.
  2. Confirmez la baseline native envoyée à Capgo.
  3. Associez l’appareil de test au canal prévu.
  4. Vérifiez la cible du canal et sa stratégie de version.
  5. Demandez une mise à jour et confirmez le résultat sur l’appareil.

Effectuez le même contrôle sur une autre baseline native si votre base d’utilisateurs comporte plusieurs versions store en circulation. Un bundle fonctionnel sur un build récent peut être bloqué sur un binaire plus ancien, et c’est peut-être la règle de sécurité attendue.

Pour des releases plus larges, commencez par un canal de test ou un déploiement progressif limité. Surveillez les résultats d’éligibilité inattendus avant d’élargir l’audience. Le modèle de canaux de Capgo permet aux équipes de diriger les bundles via des canaux de release ; gardez la cible de chaque canal et la ligne native prévue claires dans vos notes de version.

Si un appareil de test ne se met pas à jour, vérifiez son affectation de canal et ses valeurs de version avant de réenvoyer le bundle. Publier le même bundle à répétition ne corrigera pas un décalage de baseline.

Étape 6 : Diagnostiquez les écarts de version et rendez vos releases reproductibles

Lorsque les valeurs ne correspondent pas à vos attentes, tracez-les dans l’ordre. Commencez par confirmer la version de l’app native sur l’appareil. Vérifiez ensuite si un override de configuration modifie la valeur de base. Comparez enfin la version du bundle reçue par Capgo avec la cible du canal. Cette séquence permet de distinguer une valeur source erronée d’une règle de canal qui fonctionne comme configurée.

Les causes courantes incluent l’augmentation de package.json tout en laissant la version native inchangée, en compilant une plateforme depuis une branche de release différente, et en testant un appareil associé à un autre canal. Autre source de confusion : appeler chaque nombre une « version de build ». Notez quelle valeur est native, laquelle correspond au bundle uploadé, et laquelle est réellement installée.

Pour la CI/CD, rendez les entrées de version explicites. Laissez le pipeline lire la version de release prévue depuis une source contrôlée, puis passez-l’à la commande d'upload ou mettez à jour le champ package avant l'étape d'upload. Enregistrez la baseline native résolue et la cible du bundle dans la sortie du job. Évitez de dépendre de l'état local d'un développeur que le serveur de build ne voit pas.

Utilisez une release gate qui échoue quand une version requise manque ou a un format que votre équipe n'accepte pas. Faites ensuite un upload de test sur le bon canal avant la promotion. Capgo prend en charge un flux de déploiement basé sur CLI, ce qui permet aux équipes d'intégrer l'upload du bundle dans leur job CI/CD existant et de garder un log de commandes visible.

Ne confondez pas ces valeurs avec la version du moteur WebView d'Android. Notre @capgo/capacitor-webview-version-checker plugin vérifie si le moteur WebView d'un appareil est obsolète et peut afficher un prompt de mise à jour native. C'est une question distincte de version_build et version_name, ce qui n'empêche pas la vérification du baseline natif et du bundle cible du canal.

Lors d’une migration depuis un ancien schéma, ne renommez pas toutes les valeurs existantes en une seule passe. Mappez d’abord l’ancienne version native à la baseline native. Mappez ensuite la release web uploadée à la version du bundle. Testez des builds d’app existants représentatifs avec la stratégie de canal avant d’y diriger les utilisateurs.

Conservez une fiche de release concise avec le commit source, la version native, la version du bundle uploadé, le canal et le résultat des tests. Si une release doit être mise en pause ou faire l’objet d’un rollback, cette fiche aide l’équipe à identifier quel bundle est allé où. Elle rend aussi le prochain déploiement reproductible plutôt que dépendant de la mémoire de quelqu’un pour savoir quel fichier a été modifié.

FAQ

Quelle est la différence entre version_build et version_name dans Capgo ?

version_build est la baseline de l’app native, tandis que version_name est la version actuelle du bundle téléchargé. Capgo utilise la baseline native lorsqu’il vérifie si le bundle cible d’un canal est éligible. Gardez ces deux valeurs séparées dans les logs et les notes de release pour savoir quelle app native est installée et de quel bundle web elle dispose.

version_name contrôle-t-il si une mise à jour OTA est autorisée ?

Non, les stratégies de version de canal de Capgo comparent le bundle cible avec version_build, la baseline native. version_name identifie le bundle téléchargé actuel. Si un appareil ne reçoit pas de mise à jour, vérifiez sa baseline, sa cible de canal et la stratégie configurée avant de modifier la valeur du bundle actuel.

D’où Capgo récupère-t-il la version native ?

Sur iOS, Capgo lit CFBundleShortVersionString, que Xcode renseigne généralement à partir de MARKETING_VERSION. Sur Android, la version native provient de defaultConfig.versionName. Une version explicite de l’updater dans la configuration Capacitor peut changer la valeur que votre application envoie. Vérifiez donc l’application compilée.

Où Capgo récupère-t-il la version du bundle ?

Capgo peut utiliser le version champ dans package.json si vous ne transmettez pas de version de bundle explicite. Vous pouvez aussi fournir la version avec l’option de CLI --bundle . Choisissez une source unique et claire pour votre workflow de release, puis vérifiez la version reçue par Capgo après l’upload.

Conclusion

Utiliser version_build pour la baseline native et version_name pour le bundle installé. Avant votre prochain déploiement progressif, vérifiez les deux valeurs sur un appareil de test et comparez la cible du canal avec la baseline. Ce simple contrôle permet de détecter une incompatibilité de version avant qu’elle n’atteigne un public plus large.

Live updates pour les apps Capacitor

Lorsqu'un bug de la couche web est en ligne, déployez le correctif via Capgo au lieu d'attendre des jours l'approbation des stores. Les utilisateurs reçoivent la mise à jour en arrière-plan, tandis que les changements natifs suivent le circuit de validation habituel.

Les derniers articles du blog

Capgo vous offre les meilleures informations pour créer une application mobile vraiment professionnelle.