Capgo version_build vs version_name : étapes de configuration

Capgoles noms de version peuvent sembler contre-intuitifs au début : version_build est la base de l'application native, tandis que version_name suit le bundle sur l'appareil. Maîtrisez cette distinction pour comprendre pourquoi un appareil recevra, ou non, une mise à jour OTA avant votre déploiement.

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

Table des matières

• Étape 1 : Localisez version_build et version_name dans Capgo
• Étape 2 : Identifiez la baseline native 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

Start by treating these as two different facts about one app install. version_build indique à Capgo quelle version de l'app native est sur l'appareil. version_name indique à Capgo quel bundle JS l'appareil a téléchargé. Ils peuvent avoir des valeurs différentes, ce qui est souvent normal.

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.

Conservez ces trois valeurs dans des colonnes distinctes dans une release note ou un rapport de test. Si l'équipe n'écrit qu'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.

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

Étape 2 : Identifier le baseline natif 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'app native est le binaire iOS ou Android installé. Le bundle contient les assets web qu'une app Capacitor peut recevoir via une mise à jour OTA.

Imaginez une app native déployée avec un baseline 1.2.3. Un correctif web ultérieur est envoyé en tant que bundle 1.2.4. Capgo vérifie si le bundle cible du canal est autorisé pour le baseline natif 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. Le baseline natif reste lié au binaire installé.

Cette différence est cruciale lorsqu'un utilisateur possède un build app-store 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 réglage natif, prévoyez un Native Build plutôt que de considérer un upload de bundle comme un substitut.

Utilisez ce test 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 natif.
• Vérifiez la version du bundle assignée au canal de l'appareil.
• Enregistrez la version du bundle installé séparément des deux autres.

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

Une fois que vous pouvez nommer la version de référence et le bundle actuel, l'étape suivante consiste à remonter chaque valeur jusqu'à son fichier source. C'est là que les différences entre plateformes apparaissent généralement.

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

Pour une fiabilité version_build, trouvez la version native rapportée par votre application Capacitor. La documentation des versions de Capgo décrit différentes clés sources pour iOS et Android, puis utilise la valeur native résultante comme base de comparaison pour les Live Updates.

Sur iOS

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

Lorsqu'une équipe met à jour le projet Xcode mais pas la valeur qui atteint l'application, la vue locale du projet peut sembler correcte alors que le binaire installé rapporte autre chose. Comparez la version dans l'application 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'application Android. Ce nom de version natif est utilisé pour la comparaison OTA de Capgo. Ne le confondez pas avec un code de build Android ou une version de package JavaScript sans rapport. Pour ce contrôle, la question cruciale est de savoir quel nom de version l'application native envoie.

Une politique de version partagée peut aider les deux plateformes à rester alignées, mais ne supposez pas qu'elles partagent déjà une source unique. iOS et Android peuvent avoir des fichiers, des étapes de build ou des calendriers de release distincts. Comparez leurs valeurs finales lors du contrôle de la release, surtout si une plateforme a un calendrier de déploiement progressif différent sur les stores.

Some apps explicitly set the native version in capacitor.config.ts via la valeur version de la configuration de l'updater. Le Capgo Testeur Semver décrit cette base native comme une valeur pouvant provenir de la configuration ou des métadonnées de l'application 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 permet de tracer plus facilement un écart après une release, lorsque le dépôt peut déjà contenir une version plus récente que 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 terminée alors que la version native packagée reste inchangée.

Étape 4 : Définir et vérifier 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.
• Use a minor change when the change belongs to a new compatible feature line.
• Utilisez un changement majeur lorsque la limite de compatibilité change et que les anciens code natifs pourraient ne pas supporter le bundle.

Ces labels sont une convention d'équipe, pas un moyen d'ajouter des capacités natives via OTA. Un numéro de version ne peut pas prouver qu'un bundle est sûr pour une application native. Liez vos décisions réelles de compatibilité au code et aux dépendances du 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é sur un canal non prévu peut tout de même fausser les résultats de vos tests.

Des chaînes invalides ou incohérentes nécessitent un arrêt pour vérification, pas une supposition. Conservez une valeur de release connue pour être stable, 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é du canal est une comparaison, pas une supposition basée sur l'apparence du bundle le plus récent. Capgo compare le bundle cible du canal avec la base native envoyée en tant que version_build. Le bundle actuellement téléchargé, rapporté comme version_name, n'est pas la base de 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, comparez la cible par rapport à la base native 1.2.3, et pas seulement 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 base native. Avec une stratégie major, une cible ayant une version major plus élevée peut être bloquée. Avec une stratégie minor, une cible qui modifie la version major ou minor de la base peut être bloquée. Vérifiez la stratégie configurée plutôt que de supposer que chaque bundle plus récent sera accepté.

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

1. Installez le build natif qui représente les utilisateurs que vous ciblez.
2. Confirmez la base native envoyée à Capgo.
3. Assignez 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 test sur une autre base native si votre base d'utilisateurs utilise plusieurs versions du store. Un bundle qui fonctionne sur un build récent peut être bloqué sur un binaire plus ancien, ce qui peut être une règle de sécurité voulue.

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 ; précisez clairement la cible et la ligne native prévue pour chaque canal dans vos notes de release.

Si un appareil de test ne se met pas à jour, vérifiez son affectation au canal et les valeurs de version avant de renvoyer l'upload. Publier plusieurs fois le même bundle ne résoudra pas un problème d'incompatibilité de baseline.

Étape 6 : Diagnostiquer les écarts de version et rendre les releases reproductibles

Lorsque les valeurs ne correspondent pas à vos attentes, tracez-les dans l'ordre. Confirmez d'abord la version de l'app native sur l'appareil. Vérifiez ensuite si un override de configuration modifie la baseline. Comparez ensuite la version du bundle reçue par Capgo avec la cible du canal. Cette séquence permet de distinguer une mauvaise valeur source d'une règle de canal qui fonctionne comme prévu.

Les causes courantes incluent l'incrémentation 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 remplit généralement à partir de MARKETING_VERSION. Sur Android, la version native provient de defaultConfig.versionName. Une version d'updater explicite dans la configuration Capacitor peut modifier la valeur envoyée par votre app, vérifiez donc bien l'app compilée.

D'où Capgo récupère-t-il la version du bundle ?

Capgo peut utiliser la version champ dans package.json lorsque vous ne passez pas de version de bundle explicite. Vous pouvez également fournir la version avec les CLI --bundle de Capgo. Choisissez une source unique pour votre workflow de release, puis vérifiez la version reçue par Capgo après l'upload.

Conclusion

Utiliser version_build pour la base 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 base. Ce simple contrôle permet de détecter un décalage de version avant qu'il n'atteigne une audience plus large.