Compatibilité native

Une mise à jour en temps réel Capgo remplace votre paquet JavaScript instantanément, mais elle ne peut pas changer la partie native de votre application — les plugins __CAPGO_KEEP_0__/Cordova, les dépendances natives et la configuration du projet native qui sont compilés dans le fichier binaire installé. Lorsqu'un nouveau paquet attend des __CAPGO_KEEP_1__ natives que le fichier binaire installé n'a pas, le paquet est part of your app — the Capacitor/Cordova plugins, native dependencies, and native project configuration that are compiled into the installed binary. When a new bundle expects native code that the installed binary doesn’t have, the bundle is : __CAPGO_KEEP_0__ peut toujours le livrer, mais il peut planter ou se comporter de manière anormale sur les appareils qui exécutent toujours la version native plus ancienne.Install, synchronisez et suivez le guide de la source pour utiliser Capgo.

Cette page explique comment Capgo détecte la compatibilité native, ce que signifie une mise à jour incompatible pour vos utilisateurs, et comment livrer des changements natifs de manière sûre.

Remarque

Les mises à jour en temps réel sont limitées aux modifications du paquet JavaScript. Si vous avez besoin d'actualiser la version native de code — ajout ou suppression d'un plugin, mise à niveau de Capacitor, ou modification de la configuration du projet native — vous devrez soumettre une nouvelle build binaire par le processus de distribution habituel des magasins d'applications.

Pourquoi la compatibilité native compte

Chaque application Capacitor est livrée en deux couches :

• Le binaire natif que les utilisateurs téléchargent depuis l'App Store / Play Store. Il contient Capacitor, vos plugins natifs et votre configuration native.
• Le paquet JavaScript (votre application web) qui peut être mise à jour en ligne Capgo.

Une mise à jour en direct n'échange que la couche JavaScript. Si ce nouveau JavaScript appelle un plugin natif ou API qui n'est pas compilé dans le code binaire installé, l'appel échoue en temps de exécution — ce qui peut faire planter l'application ou briser silencieusement une fonctionnalité. En résumé : Capgo ne peut pas mettre à jour les plugins natifs code, donc un appareil exécutant la version native ancienne ne peut pas exécuter en toute sécurité un bundle construit contre de nouveaux plugins natifs code.

Comment Capgo détecte la compatibilité

Lorsque vous téléchargez un bundle — ou que vous exécutez la vérification manuellement — Capgo compare les packages natifs dans votre projet local (vos plugins Cordova Capacitor et leurs versions) avec les packages natifs enregistrés pour le bundle actuellement en ligne sur le canal:

• Si elles correspondent, la mise à jour est JavaScript uniquement et sûre à envoyer en ligne.
• Si un plugin a été ajouté, supprimé ou a changé de version, le bundle est incompatible avec les plugins natifs — ces changements ne prennent effet qu'une fois que les utilisateurs installent un nouveau binôme natif.

Vérifiez à partir du CLI

bunx @capgo/cli@latest bundle compatibility com.example.app --channel production

La CLI imprime une table de chaque paquet natif avec sa version locale, la version en direct sur le canal et un statut :

Package              Local    Remote   Status
@capacitor/core      6.1.2    6.1.2    ✅
@capacitor/share     6.0.0    6.0.0    ✅
@capacitor/camera    6.1.0    —        ❌  not in the live bundle

Conseil

Ajouter --text pour échanger les émoticônes pour OK/FAIL (pratique dans les journaux CI), et --package-json / --node-modules pour pointer les chemins corrects dans un monorepo.

Obtenez un verdict lisible par machine (CI)

Pour les pipelines, bundle releaseType réduit la vérification en une seule parole :

bunx @capgo/cli@latest bundle releaseType com.example.app --channel production
# → OTA      safe to ship as a live update
# → native   needs a new app-store build

Gardez votre pipeline de mise en production sur cette ligne : envoyer une mise à jour en direct lorsque cela imprime OTAet déclenchez une construction native lorsque cela imprime native.

Quelle que soit l'update incompatibles signifie pour vos utilisateurs

Attention

Par défaut, la détection d'incompatibilité ne bloque pas l'envoi — si vous envoyez un bundle incompatibles natif et le définissez comme la version active d'un canal, __CAPGO_KEEP_0__ livrera block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo aux appareils de ce canal. (Vous pouvez transformer cela en un verrou dur avec — voir --fail-on-incompatible Prévenir les livraisons incompatibles ci-dessous.) Sur les appareils qui exécutent toujours le

binaire natif plus ancien , la partie manquante du code __CAPGO_KEEP_0__ peut provoquer des plantages ou des fonctionnalités cassées — même si l'update a téléchargé et appliqué « avec succès ». C'est pourquoi une mise à jour en direct peut être en direct et livrée et encore casser l'application pour les utilisateurs existants, et pourquoi __CAPGO_KEEP_1__ peut vous avertir lorsque un bundle incompatibles est mis en ligne., the missing native code can cause crashes or broken features — even though the update downloaded and applied “successfully.” This is why a live update can be live and delivered yet still break the app for existing users, and why Capgo can warn you when an incompatible bundle goes live.

Capgo’s le rôle de rollback automatique peut capturer une erreur JavaScript lancée avant notifyAppReady() s'exécute, mais ce n'est pas un substitut pour la livraison de versions natives compatibles code — une incompatibilité qui fait crash plus tard, ou crash nativement, peut lui échapper.

Comment livrer des changements natives en toute sécurité

Publier une nouvelle version native (la vraie correction)

Lorsqu'une bundle nécessite de nouvelles dépendances natives code, construire et soumettre une nouvelle version binaire sur l'App Store / Play Store (ou reconstruire avec Capgo Cloud Build). Une fois que les utilisateurs mettent à jour la version binaire, les dépendances natives de la bundle s'alignent et la mise à jour en direct fonctionne correctement.

Revenir en arrière si une bundle incompatible est déjà en ligne

Si une bundle incompatible est déjà active sur un canal, rétablir le canal sur la dernière version compatible pour arrêter de la servir jusqu'à ce que la version native soit disponible. Voir Rollbacks.

Prévenir les livraisons incompatibles

Deux garde-fous complémentaires, qui inspectent tous deux vos packages natifs :

Faire fail l'upload en CI — --fail-on-incompatible

Ajoutez la flag à votre bundle upload étape. Si les packages natifs du bundle ne correspondent pas à la version actuellement en ligne du canal, l'upload fail avec un code de sortie non nul et rien n'est expédié — afin que votre pipeline vous empêche de publier silencieusement une mise à jour OTA qui ne peut prendre effet que lorsque les utilisateurs installent une build native :

bunx @capgo/cli@latest bundle upload --channel production --fail-on-incompatible

Livraisons compatibles — et les cas où la vérification ne peut pas être exécutée (un nouveau canal, ou aucune métadonnée distante) — passent inaltérées. Dans un terminal interactif, elle propose au lieu de cela le flux de construction native-build du Capgo Builder ; refuser échoue. (Ne peut pas être combiné avec) --ignore-metadata-check.)

La livraison par version native — metadata + --auto-min-update-version

Lorsque vous faites envoyer la version native et le bundle ensemble, placez le canal sur la metadata stratégie et envoyez avec --auto-min-update-version. Capgo effectue la vérification de compatibilité à chaque envoi et, lorsque le bundle nécessite de nouvelles versions natives code, élèvez le niveau de mise à jour afin que les appareils qui n'ont pas installé la version native correspondante ne la reçoivent pas :

# one-time: switch the channel to the metadata strategy
bunx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadata

# from then on, Capgo sets the floor automatically on every upload
bunx @capgo/cli@latest bundle upload --channel production --auto-min-update-version

Attention

Règles de numéro de version comme --disable-auto-update major are pas un substitut — ils n'empêchent que les sauts de version et n'inspectent jamais le __CAPGO_KEEP_0__ natif, donc une modification native déployée dans une mise à jour mineure ou de maintenance est toujours envoyée. Utilisez a substitute — they only block version jumps and never inspect native code, so a native change shipped in a minor or patch release still goes out. Use --fail-on-incompatible , qui vérifient vos packages natifs. --auto-min-update-versionVoir

Ciblage de version pour l'ensemble des options de ciblage. Section liée intitulée « Section liée »

Ciblage de version

Rollbacks

Remontées

Ciblage de version

Rétablir un canal vers la dernière build compatible si un bundle incompatible est allumé.

Mise à jour des types

Comment les conditions de timing, de retard et de blocage de version fonctionnent ensemble.

CLI: bundle

Référence pour la compatibilité du bundle, releaseType et les options d'upload.

Continuez de la compatibilité native

Compatibilité native pour garder les mises à jour en direct en sécurité, connectez-le avec Ciblage de version pour acheminer les bundles par version native, Si vous utilisez Rollbacks pour se rétablir lorsqu'un bundle incompatible est expédié, Types d'actualisation pour comprendre la version du canal bloquante, et les Capgo CLI référence du bundle pour les commandes de compatibilité et de releaseType.