Compatibilité native

Copiez un prompt de configuration avec les étapes d'installation et le guide Markdown complet pour ce plugin.

Un Capgo live update remplace votre application par bundle JavaScript instantanément, mais il ne peut pas changer la native 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 native-incompatible: Capgo peut toujours le délivrer, mais il peut planter ou se comporter de manière anormale sur les appareils qui utilisent encore la version native plus ancienne.

This page explains how Capgo detects native compatibility, what an incompatible update means for your users, and how to ship native changes safely.

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, envoyez-le sous forme de live update.

Utilisez une mise à jour native lorsque la modification met à jour capacitor.config.ts, la configuration du plugin stockée dans Capacitor config, les plugins ou les dépendances natifs, Capacitor lui-même ou les fichiers de projet iOS/Android. Un contrôle pratique : si la modification doit mettre à jour le projet natif par npx cap sync ou npx cap copy before installed devices can use it, treat it as native.

Change	Ship with Capgo OTA?	Why
HTML, CSS, JavaScript d'application, images, polices et autres actifs de construction web	Oui	Elles sont chargées depuis le bundle web en temps de exécution.
Les modifications du package Pure-JavaScript sont regroupées dans votre sortie web	Oui	Le JavaScript généré fait partie du bundle web.
`capacitor.config.ts` changes	Non	La configuration Capacitor est lue dans l'application native en temps de build.
Ajout, suppression ou mise à jour des plugins Capacitor/Cordova	Non	Le binaire natif installé doit contenir le code natif correspondant.
Fichier de projet iOS ou Android modifié	Non	Existing users need a new binary from the stores.

Plugins clients par stack

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

Plugin	Utiliser 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é natives s'appliquent indépendamment du plugin client — elles comparant les dépendances natives enregistrées du bundle aux binaires installés.

Pourquoi la compatibilité native compte

Chaque application Capacitor embarque deux couches :

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

Un live update n'actualise 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 faille à l'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 paquet 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 Capacitor/plugins Cordova et leurs versions) avec les packages natifs enregistrés pour le bundle actuellement en direct sur le canal:

Si elles correspondent, la mise à jour est JavaScript-only et sûre à 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 ont installé un nouveau binôme natif.

Vérifiez à partir de CLI

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

La 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

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

Garez votre pipeline de mise en production sur ceci : envoyer un live update lorsque cela imprime. OTAet déclenche une construction native lorsque cela imprime. native.

et déclenchez une mise en construction native lorsque cela imprime

Sur les appareils qui exécutent toujours le binaire natif plus ancien, le code manquant peut provoquer des plantages ou des fonctionnalités brisées — même si l'actualisation a été téléchargée et appliquée « avec succès ». C'est pourquoi un live update peut être en direct et livré tout en cassant l'application pour les utilisateurs existants, et pourquoi Capgo peut vous avertir lorsque l'un de ces bundles incompatibles est mis en ligne.

le Capgo's retour automatique peut attraper une erreur JavaScript lancée avant notifyAppReady() exécuter, mais ce n'est pas un substitut à la livraison de code natifs compatibles — un désaccord qui plante plus tard, ou plante nativement, peut lui échapper.

How to ship native changes safely

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

Lorsqu'une bundle nécessite de nouvelles natives code, 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 de la bundle s'alignent et le live update fonctionne correctement.

Annulez si une bundle incompatible est déjà en ligne

Si une bundle incompatible est déjà active sur un canal, rétablissez le canal à la dernière mise à jour compatible pour arrêter de la servir jusqu'à la sortie de la mise à jour native. Voir Annulations.

Empêchez les livraisons incompatibles

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

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

Ajoutez le flag à votre bundle upload Si les packages natifs 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é — donc 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

Uploads compatibles — et les cas où le contrôle ne peut pas s'exécuter (un nouveau canal, ou pas de métadonnées distantes) — passent inaltérés. Dans une fenêtre de terminal interactive, il propose au lieu de cela le flux de build native de l'éditeur Capgo ; refuser échoue. (Ne peut pas être combiné avec --ignore-metadata-check.)

La livraison est gérée par la version native — metadata + --auto-min-update-version

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

# 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

See Version ciblée pour l'ensemble complet d'options de ciblage.

Flux natif + mise à jour OTA

Canaux Dev/production, quand conserver --fail-on-incompatible, et comment livrer une base native intentionnelle.

Auto OTA ou Natif

Wire bundle releaseType sur GitHub Actions ou GitLab afin que CI sélectionne live update plutôt que Capgo Build.

Ciblage de version

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

Rollbacks

Rétablir un canal à la dernière mise à jour compatible si un paquet incompatible est mis en ligne.

Mises à Jour

Comment les conditions de timing, de retard et de blocage de version s'entrelacent.

CLI: paquet

Référence pour la compatibilité du paquet, type de version, et options d'upload.

Continuez de la compatibilité native

Si vous utilisez Compatibilité native pour garder les mises à jour en vie, connectez-l’à Version ciblée Pour router des bundles par version native, Rollbacks Lorsqu'un bundle incompatible est déployé. Mises à Jour pour comprendre la blocage de version du canal, et le Capgo CLI référence du bundle pour les commandes de compatibilité et de releaseType.