Compatibilité native

Une mise à jour live Capgo remplace le bundle JavaScript de votre application Installez, synchronisez et suivez la guide source complète à partir d'une seule commande copiable. instantly, mais elle ne peut pas changer la nativement partie de votre application — les plugins Cordova Capacitor, les dépendances natives et la configuration de projet native qui sont compilées dans le fichier binaire installé. Lorsqu'un nouveau bundle attend des code natives que le fichier binaire installé n'a pas, le bundle est incompatible avec le code natif: Capgo peut toujours les livrer, mais il peut planter ou se comporter de manière anormale sur les appareils qui sont toujours en cours d'exécution de la version native plus ancienne.

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 natives de manière sûre.

Note

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

TLDR : OTA ou natif ?

Capgo peut envoyer des fichiers à partir du dossier de génération de votre build web. Si la modification ne concerne que l'HTML, le CSS, le JavaScript, les assets ou les packages pure-JavaScript intégrés à cet output, livre-le en tant que mise à jour en temps réel.

Utilisez une mise en production d'application native lorsque des modifications mettent à jour capacitor.config.tsla configuration du plugin stockée dans Capacitor config, les plugins natifs ou les dépendances, Capacitor lui-même, ou les fichiers de projet iOS/Android. npx cap sync Une vérification pratique : si la modification doit mettre à jour le projet natif par npx cap copy ou

avant que les appareils installés puissent l'utiliser, traitez-la comme native.	Ship with Capgo OTA?	Envoyez avec __CAPGO_KEEP_0__ OTA ?
Pourquoi	HTML, CSS, le JavaScript de l'application, les images, les polices et autres actifs de construction web	Oui
Ils sont chargés à partir du paquet web en temps de exécution.	Les modifications de package Pure-JavaScript bundlées dans votre sortie web	The code généré JavaScript fait partie du bundle web.
capacitor.config.ts changements	Non	La configuration Capacitor n'est pas lue dans l'application native à l'étape de construction.
Ajouter, supprimer ou mettre à jour Capacitor / Cordova plugins	Non	L'exécutaire natif installé doit contenir le code natif correspondant.
Les modifications des fichiers de projet iOS ou Android	Non	Les utilisateurs existants ont besoin d'un nouveau binaire depuis les magasins.

Plugins de client par stack

Capgo démarre des clients de mise à jour dédiés pour chaque runtime hybride :

Plugin	Utilisez lorsque
@capgo/capacitor-updater	Capacitor applications iOS/Android
@capgo/cordova-updater	Applications iOS 7+ / Android 13+ Cordova
@capgo/electron-updater	Applications Electron bureautiques

Les vérifications de compatibilité native s'appliquent quel que soit le plugin du client — elles comparant les dépendances natives enregistrées du paquet avec le code binaire installé.

Pourquoi la compatibilité native compte

Chaque application Capacitor embarque deux couches :

• Le code binaire natif Les utilisateurs installent depuis l'App Store / Play Store. Il contient Capacitor, vos plugins natifs, et votre configuration native.
• Le bundle JavaScript (votre application web) qui Capgo peut mettre à jour par Wi-Fi.

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

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 modification est uniquement JavaScript et sûr de l'envoyer par voie aérienne.
• Si un plugin a été ajouté, supprimé ou a changé de version, le bundle est incompatible avec le natif — 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

Le CLI imprime une table de chaque package 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 vers les bons chemins dans un monorepo.

Obtenez un verdict lisible par machine (CI)

Pour les pipelines, bundle releaseType réduit le contrôle 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

Contrôlez votre pipeline de mise en production sur cela : lancer une mise à jour en direct lorsque cela imprime OTA, et déclenchez une construction native lorsque cela imprime native.

What une mise à jour incompatible signifie pour vos utilisateurs

Attention

Par défaut, la détection d'incompatibilité ne bloque pas l'envoi — si vous envoyez un bundle incompatibles native et le définissez comme la version active d'un canal, __CAPGO_KEEP_0__ block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo à des appareils sur ce canal. (Vous pouvez transformer cela en un verrou dur avec — voir --fail-on-incompatible Empêcher les livraisons incompatibles ci-dessous.) Empêcher les livraisons incompatibles ci-dessous.

On les appareils qui utilisent toujours la version native binaire plus ancienne, la mise à jour native __CAPGO_KEEP_0__ manquante peut provoquer des plantages ou des fonctionnalités cassées — même si l'update téléchargé et appliqué a réussi « avec succès ». C'est pourquoi une mise à jour en direct peut être en direct et livrée, mais toujours briser l'application pour les utilisateurs existants, et pourquoi __CAPGO_KEEP_1__ peut vous avertir lorsque le bundle incompatibles est mis en ligne. __CAPGO_KEEP_0__’s, 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 les exécutions, mais ce n'est pas un substitut pour envoyer des mises à jour natives compatibles — un désaccord qui plante plus tard, ou plante nativement, peut lui échapper. Comment envoyer des mises à jour natives de manière sûre notifyAppReady() runs, but it isn’t a substitute for shipping compatible native code — a mismatch that crashes later, or crashes natively, can slip past it.

Publiez une nouvelle mise à jour native (la vraie solution)

Lorsqu'un bundle nécessite de nouvelles mises à jour natives __CAPGO_KEEP_0__, construisez et soumettez une nouvelle version binaire sur l'App Store / Play Store (ou reconstruisez avec __CAPGO_KEEP_1__ Cloud Build). Une fois que les utilisateurs mettent à jour la version binaire, les dépendances natives du bundle se mettent en ligne et la mise à jour en direct fonctionne correctement.

When a bundle needs new native code, build and submit a new binary to the App Store / Play Store (or rebuild with Capgo Cloud Build). Once users update the binary, the bundle’s native dependencies line up and the live update runs correctly.

Si un paquet incompatibles est déjà en ligne, revenez en arrière.

Si un paquet incompatibles est déjà actif sur un canal, rétablissez le canal à la dernière version compatible pour l'arrêter de le servir jusqu'à ce que la mise à niveau native soit disponible. Consultez Rollbacks.

Empêchez les livraisons incompatibles

Deux garde-fous complémentaires, qui inspectent tous deux vos paquets natives :

Échouez l'upload en CI — --fail-on-incompatible

Ajoutez la flag à votre bundle upload étape. Si les paquets natives du bundle ne correspondent pas à la version actuellement en ligne du canal, l'upload échoue 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 pas prendre effet avant que les utilisateurs installent une mise à niveau native :

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

Les téléchargements compatibles — et les cas où le contrôle ne peut pas s'exécuter (un nouveau canal, ou aucune métadonnée distante) — passent intactes. Dans un terminal interactif, il propose la mise à jour native du Capgo Builder au lieu de cela ; refuser échoue. (Ne peut pas être combiné avec --ignore-metadata-check.)

Livraison par version native — metadata + --auto-min-update-version

Lorsque vous faites envoyer la mise à jour native et le bundle ensemble, placez le canal sur la metadata stratégie et téléchargez avec --auto-min-update-version Capgo exécute le contrôle de compatibilité sur chaque téléchargement et, lorsqu'une mise à jour de bundle nécessite de nouvelles mises à jour natives code, élève le plancher d'actualisation afin que les appareils qui n'ont pas installé la mise à jour 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

Les règles de numéro de version comme --disable-auto-update major ne constituent pas un substitut — elles n'empêchent que les sauts de version et n'inspectent jamais le code natif __CAPGO_KEEP_0__, donc une modification native déployée dans une mise à jour mineure ou de correction continue à être déployée. Utilisez ou 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 Voir --auto-min-update-versionVersion Targeting

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

Section liée

Version Ciblage

Deliver only bundles compatible using channels, semver rules, and the strategy of metadata.

Rollbacks

Revert a channel to the last build compatible if a bundle incompatible went live.

Types d'actualisation

Expliquez comment les conditions de retard, les conditions de retard et le 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 Compatibilité native pour garder les mises à jour en direct en sécurité, connectez-le à Version Ciblée pour router les bundles en fonction de la version native, Annulations pour récupérer lorsque le bundle incompatibilité est expédié, Types de Mise à Jour pour comprendre la version du canal bloquant, et le Capgo CLI référence du bundle pour les commandes de compatibilité et de releaseType.