Compatibilité native

Une mise à jour en temps réel Capgo remplace le bundle JavaScript de votre application. Configurez avec l'IA instantanément, mais il 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és dans le fichier binaire installé. Lorsqu'un nouveau bundle attend des code natives que le fichier binaire installé n'a pas, le bundle est non-natif: Capgo peut toujours le livrer, mais il peut planter ou se comporter de manière anormale sur les appareils qui sont toujours en train de fonctionner avec 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

Mises à jour en temps réel sont limitées aux changements de bundle JavaScript. Si vous avez besoin d'actualiser code natives — en ajoutant ou en supprimant un plugin, en mettant à jour Capacitor, ou en changeant la configuration de projet native — vous devrez soumettre un nouveau build binaire via 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 le changement 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 une modification met à jour capacitor.config.tsLa configuration du plugin est 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	Le HTML, le CSS, le JavaScript d'application, les images, les polices et autres actifs de build web	Oui
Ils sont chargés à partir du paquet web en temps de exécution.	Les changements de package Pure-JavaScript encapsulés dans votre sortie web	The code généré JavaScript fait partie du bundle web.
capacitor.config.ts changements	Non	La configuration Capacitor est 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 provenant des magasins.

Plugins clients par stack

Capgo fournit 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

Tout Capacitor application embarque deux couches :

• Le 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 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 d'autres termes : 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:

• S'ils correspondent, la modification est uniquement JavaScript et sûr de naviguer en ligne.
• 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 la vérification en un seul mot :

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 ceci : envoyer une mise à jour en direct lorsque cela imprime OTAet 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'upload — si vous uploadez un bundle incompatible natif et le définissez comme la build active d'un canal, __CAPGO_KEEP_0__ ne 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 une porte d'entrée fermée avec — voir --fail-on-incompatible Empêcher les livraisons incompatibles ci-dessous.) Empêcher les livraisons incompatibles ci-dessous

On les appareils qui fonctionnent toujours avec le binaire natif plus ancien, le code natif manquant peut provoquer des plantages ou des fonctionnalités cassées — même si l'actualisation a été téléchargée et appliquée avec succès. C'est pourquoi une mise à jour en direct peut être en direct et livrée, mais toujours casser l'application pour les utilisateurs existants, et pourquoi Capgo peut vous avertir lorsque le bundle incompatibles est en ligne.

le rôle de Capgo’s retour automatique peut attraper une erreur JavaScript lancée avant notifyAppReady() exécuter, mais ce n'est pas un substitut pour envoyer des code natifs compatibles — un désalignement qui plante plus tard, ou plante nativement, peut lui échapper.

Comment envoyer des changements natifs de manière sûre

Publiez une nouvelle build natif (la vraie solution)

Lorsqu'un bundle nécessite de nouveaux code natifs, construisez et soumettez une nouvelle version binaire sur l'App Store / Play Store (ou reconstruisez avec Capgo 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.

Si un bundle incompatibles est déjà en ligne, annulez-le.

Si un bundle 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 version native soit disponible. Consultez Rollbacks.

Empêchez les livraisons incompatibles

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

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

Ajoutez la flag à votre bundle upload étape. Si les packages 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 prendre effet que lorsque les utilisateurs installent une version native :

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

Les téléchargements compatibles — et les cas où la vérification 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 en œuvre de flux de construction native du Capgo 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 construction native et le bundle ensemble, placez le canal sur la metadata stratégie et téléchargez avec --auto-min-update-versionCapgo exécute la vérification de compatibilité sur chaque téléchargement et, lorsqu'un bundle nécessite de nouvelles constructions natives code, élève le plan d'actualisation pour que les appareils qui n'ont pas installé la construction native correspondante ne 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 ne bloquent que les sauts de version et n'inspectent jamais les __CAPGO_KEEP_0__, donc une modification native déployée dans une mise à jour mineure ou de correction est toujours envoyé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 titrée « Section liée » Section liée

Section liée

Mise à jour OTA ou Native

Wire bundle releaseType dans GitHub Actions ou GitLab afin que CI détecte la mise à jour en direct plutôt que Capgo Build.

Ciblage de version

Fournir uniquement des ensembles de fichiers compatibles en utilisant des canaux, des règles semver et la stratégie de métadonnées.

Rollbacks

Rétablir un canal vers la dernière version compatible si un ensemble de fichiers incompatibles est mis en ligne.

Types de mise à jour

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

CLI: ensemble de fichiers

Référence pour la compatibilité de l'ensemble de fichiers, le type de version et les options d'upload.

Continuez à partir de la compatibilité Native

Si vous utilisez Compatibilité native pour garder les mises à jour en direct en sécurité, connectez-la avec Ciblage de version pour router les bundles en fonction de la version native, Rollbacks pour récupérer lorsque des bundles incompatibles sont expédiés, Types d'actualisation pour comprendre le blocage de version par canal, et le Capgo CLI référence de bundle pour les commandes de compatibilité et de releaseType. for the compatibility and releaseType commands.