Compatibilité native

Un Capgo live update remplace l’application bundle JavaScript instantanément, mais il ne peut pas modifier natif partie de votre application — les plugins Capacitor/Cordova, les dépendances natives et la configuration du projet natif qui sont compilés dans le binaire installé. Si un nouveau bundle nécessite des code natifs que le binaire installé ne contient pas, le bundle est incompatible avec le natif: Capgo peut toujours le livrer, mais il peut planter ou dysfonctionner sur les appareils qui exécutent encore l’ancien build natif.

Cette page explique comment Capgo détecte la compatibilité native, ce qu’une mise à jour incompatible signifie pour vos utilisateurs et comment déployer des modifications natives en toute sécurité.

Remarque

Les live updates sont limitées aux modifications du bundle JavaScript. Si vous devez mettre à jour des code natifs — ajouter ou supprimer un plugin, mettre à niveau Capacitor ou modifier la configuration du projet natif — vous devrez soumettre un nouveau build binaire via le processus habituel de distribution sur les stores.

TLDR : OTA ou natif ?

Capgo peut envoyer des fichiers depuis votre dossier de build web généré. Si la modification ne concerne que le HTML, le CSS, le JavaScript, les assets ou les packages JavaScript purs intégrés à cette sortie, déployez-la comme live update.

Utilisez une release d'app native lorsqu'une modification met à jour capacitor.config.tsla configuration de plugin stockée dans la config Capacitor, les plugins ou dépendances natifs, Capacitor lui-même, ou les fichiers de projet iOS/Android. Test pratique : si la modification doit mettre à jour le projet natif via npx cap sync ou npx cap copy avant que les appareils installés puissent l'utiliser, considérez-le comme natif.

Modification	Déployer avec Capgo OTA ?	Pourquoi
HTML, CSS, JavaScript de l'app, images, polices et autres assets du build web	Oui	Ils sont chargés depuis le bundle web à l'exécution.
Modifications de packages en JavaScript pur intégrées à votre sortie web	Oui	Le JavaScript généré fait partie du bundle web.
capacitor.config.ts modifications	Non	La configuration Capacitor est intégrée à l’application native au moment du build.
Ajout, suppression ou mise à niveau de plugins Capacitor/Cordova	Non	Le binaire natif installé doit contenir le code natif correspondant.
Modifications des fichiers de projet iOS ou Android	Non	Existing users need a new binary from the stores.

Plugins client par stack

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

Plugin	À utiliser quand
@capgo/capacitor-updater	Applications iOS/Android Capacitor
@capgo/cordova-updater	Applications Cordova iOS 7+ / Android 13+
@capgo/electron-updater	Applications de bureau Electron

Les vérifications de compatibilité native s’appliquent quel que soit le plugin client : elles comparent les dépendances natives enregistrées dans le bundle avec le binaire installé.

Pourquoi la compatibilité native compte

Chaque application Capacitor est livrée en deux couches :

• Le binaire natif les utilisateurs l’installent depuis l’App Store / Play Store. Il contient Capacitor, vos plugins natifs et la configuration native.
• Le Bundle JavaScript (votre application web) que Capgo peut mettre à jour via OTA.

Un live update ne remplace que la couche JavaScript. Si ce nouveau JavaScript appelle un plugin natif ou API qui n'est pas compilé dans le binaire installé, l'appel échoue à l'exécution — ce qui peut faire planter l'app ou casser une fonctionnalité sans erreur visible. En résumé : Capgo ne peut pas mettre à jour le code natif, donc un appareil qui exécute l'ancien build natif ne peut pas exécuter sans risque un bundle compilé contre un nouveau code natif.

Comment Capgo détecte la compatibilité

Lorsque vous envoyez un bundle — ou que vous lancez la vérification manuellement — Capgo compare les packages natifs de votre projet local (vos plugins Capacitor/Cordova et leurs versions) avec les packages natifs enregistrés pour le bundle actuellement actif sur le canal:

• S'ils correspondent, le changement est uniquement JavaScript et peut être déployé via OTA en toute sécurité.
• 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 ont installé un nouveau binaire natif.

Vérifier depuis la CLI

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

Le CLI affiche un tableau de chaque package natif avec sa version locale, la version en ligne 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

Astuce

Ajoutez --text pour remplacer les emojis par OK/FAIL (pratique dans les logs CI), et --package-json / --node-modules pour pointer vers les bons chemins dans un monorepo.

Obtenir un verdict lisible par machine (CI)

Pour les pipelines, bundle releaseType réduit la vérification à 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

Conditionnez votre pipeline de release à ce résultat : déployez un live update s’il affiche OTA, et déclenchez un build natif s’il affiche native.

Ce qu'une mise à jour incompatible signifie pour vos utilisateurs

Attention

Par défaut, la détection d'incompatibilité pas bloque bien l'upload — si vous envoyez un bundle incompatible avec le natif et le définissez comme build actif d'un canal, Capgo le distribuera aux appareils de ce canal. (Vous pouvez transformer cela en un blocage strict avec --fail-on-incompatible — voir Prévenir les déploiements incompatibles ci-dessous.)

Sur les appareils qui exécutent encore l' ancien binaire natif, l'absence du code natif peut provoquer des crashs ou des fonctionnalités cassées — même si la mise à jour a été téléchargée et appliquée « avec succès ». C'est pourquoi une live update peut être en ligne et distribuée tout en cassant l'app pour les utilisateurs existants, et pourquoi Capgo peut vous avertir lorsqu'un bundle incompatible est mis en ligne.

de Capgo rollback automatique peut intercepter une erreur JavaScript levée avant notifyAppReady() s'exécute, mais cela ne remplace pas le déploiement de code natif compatible — une incompatibilité qui provoque un crash ultérieur, ou un crash natif, peut passer inaperçue.

How to ship native changes safely

Publier un nouveau build natif (la vraie solution)

Lorsqu'un bundle nécessite du nouveau code natif, compilez et soumettez un nouveau binaire à l'App Store / Play Store (ou reconstruisez avec le Cloud Build de Capgo). Une fois que les utilisateurs ont mis à jour le binaire, les dépendances natives du bundle correspondent et le live update s'exécute correctement.

Faire un rollback si un bundle incompatible est déjà en ligne

Si un bundle incompatible est déjà actif sur un canal, rebasculez le canal sur le dernier build compatible pour arrêter de le servir jusqu'à la sortie du build natif. Voir Rollbacks.

Prévenir les déploiements incompatibles

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

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

Ajoutez le flag à votre bundle upload étape. Si les packages natifs du bundle ne correspondent pas à la version live actuelle du canal, l'upload échoue avec un code de sortie non nul et rien n'est déployé — votre pipeline vous empêche ainsi de publier en silence une mise à jour OTA qui ne prendra effet qu'après l'installation d'un build natif par les utilisateurs :

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

Les uploads compatibles — et les cas où la vérification ne peut pas s'exécuter (nouveau canal, ou absence de métadonnées distantes) — passent tels quels. Dans un terminal interactif, il propose à la place le flux de build natif Capgo Builder ; un refus entraîne l'échec. (Ne peut pas être combiné avec --ignore-metadata-check.)

Astuce

Lorsque vous volontairement avez besoin d’un bundle différent des packages natifs live du canal (nouveau plugin, mise à niveau Capacitor, etc.), omettez --fail-on-incompatible pour cet upload de référence. Conservez le flag dans votre CI OTA quotidienne. Workflow complet du canal : Workflow canaux natifs + OTA.

Contrôlez la livraison par version native — metadata + --auto-min-update-version

Lorsque vous faire déployez le build natif et le bundle ensemble, placez le canal sur le metadata stratégie et envoyez avec --auto-min-update-versionCapgo effectue le contrôle de compatibilité à chaque upload et, lorsqu'un bundle nécessite de nouvelles code natives, relève le seuil de mise à jour pour que les appareils qui n'ont pas installé le build natif correspondant ne le 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érotation de version comme --disable-auto-update major que pas ne sont pas un substitut — elles ne bloquent que les sauts de version et n'inspectent jamais les code natives, donc un changement natif livré dans une release mineure ou patch passe quand même. Utilisez --fail-on-incompatible ou --auto-min-update-version, qui vérifient vos packages natifs.

Consultez Ciblage de version pour l'ensemble des options de ciblage.

Articles liés

Workflow natif + OTA

Canaux dev/prod, quand les conserver --fail-on-incompatible, et comment livrer volontairement une base native.

Auto OTA ou natif

Branchez bundle releaseType sur GitHub Actions ou GitLab pour que la CI choisisse live update plutôt que Capgo Build.

Ciblage de version

Ne livrez que des bundles compatibles via les canaux, les règles semver et la stratégie de métadonnées.

Rollbacks

Faire revenir un canal au dernier build compatible si un bundle incompatible a été mis en ligne.

Types de mise à jour

Comment le timing d’application, les conditions de délai et le blocage de version interagissent.

CLI : bundle

Référence pour la compatibilité des bundles, releaseType et les options d’upload.

Continuer depuis Native Compatibility

Si vous utilisez Compatibilité native pour garantir la sécurité des live updates, connectez-l’à Ciblage de version pour router les bundles par version native, Rollbacks pour récupérer lorsqu'un bundle incompatible est déployé, Types de mise à jour pour comprendre le blocage de version par canal, et les Capgo CLI références de bundle pour les commandes compatibility et releaseType.