Compatibilité native

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

Une mise à jour en temps réel Capgo remplace votre paquet JavaScript par instantanément, mais elle ne peut pas changer la partie native de votre application — les plugins Cordova __CAPGO_KEEP_0__, 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 incompatible avec le système d'exploitation A new bundle is created with the updated native dependencies and configuration. 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 The live update process is triggered when a new bundle is created or when the app is launched. A new bundle is created with the updated native dependencies and configuration.: Capgo 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.

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.

TLDR : Mises à jour 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 actifs ou les packages pure-JavaScript emballés dans cet output, livre-le sous forme de mise à jour en temps réel.

Utilisez une mise à jour native lorsque le changement 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 le changement doit mettre à jour le projet native par npx cap sync ou npx cap copy avant que les appareils installés puissent l'utiliser, traitez-le comme natif.

Modifier	Envoyer avec Capgo OTA ?	Pourquoi
HTML, CSS, JavaScript d'application, images, polices et autres actifs de construction web	Oui	Ils sont chargés à partir du paquet web en temps de exécution.
Les modifications du paquet Pure-JavaScript sont encapsulées dans votre sortie web	Oui	Le JavaScript généré fait partie du paquet web.
`capacitor.config.ts` modifications	Non	Capacitor config est lu dans l'application native en temps de construction.
Ajouter, supprimer ou mettre à jour les plugins Capacitor/Cordova	Non	Le fichier binaire 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	Utiliser lorsque
`@capgo/capacitor-updater`	Capacitor applications iOS/Android
`@capgo/cordova-updater`	Apps iOS 7+ / Android 13+
`@capgo/electron-updater`	Apps bureaux Electron

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

Pourquoi la compatibilité native compte

Chaque application Capacitor embarque deux couches :

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

A une mise à jour en temps réel, seuls les couches JavaScript sont mises à jour. Si ce nouveau JavaScript appelle un plugin natif ou API qui n'est pas compilé dans le code binaire installé, l'appel fail à l'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 les 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 modification est JavaScript uniquement et sûre à envoyer par air.
Si un plugin a été ajouté, supprimé ou a changé de version, le bundle est incompatible avec le code natif — ces changements ne prennent effet qu'une fois que les utilisateurs ont installé un nouveau code binaire 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

Obtenez un verdict lisible par machine (CI)

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

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 : envoyez une mise à jour en direct lorsque cela imprime OTAet déclenchez une construction native lorsque cela imprime native.

Quelle que soit l'importance d'une mise à jour incompatibles pour vos utilisateurs

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 mise à jour active d'un canal, __CAPGO_KEEP_0__ livrera pas block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo On les appareils qui fonctionnent toujours avec l'ancienne version binaire native, la partie native manquante __CAPGO_KEEP_0__ peut provoquer des plantages ou des fonctionnalités cassées — même si l'update téléchargé et appliqué « a réussi ». 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 va en direct. __CAPGO_KEEP_0__'s --fail-on-incompatible Vous pouvez convertir cela en une porte d'entrée dure avec — voir ci-dessous Prevent incompatible deliveries. Les mises à jour en direct peuvent être en direct et livrées et encore casser l'application pour les utilisateurs existants, et c'est pourquoi __CAPGO_KEEP_1__ peut vous avertir lorsque un bundle incompatibles va en direct. 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 c'est pourquoi __CAPGO_KEEP_1__ peut vous avertir lorsque un bundle incompatibles va en direct.

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 c'est pourquoi __CAPGO_KEEP_1__ peut vous avertir lorsque un bundle incompatibles va en direct. 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 c'est pourquoi __CAPGO_KEEP_1__ peut vous avertir lorsque un bundle incompatibles va en direct., 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 rollback automatique peut capturer une erreur JavaScript lancée avant 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.

Comment livrer des modifications natives de manière sécurisée

Publiez une nouvelle version native (la vraie correction)

Lorsqu'une archive nécessite de nouvelles dépendances 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 l'archive se mettent en ligne et l'update en direct fonctionne correctement.

Revenez en arrière si une archive incompatible est déjà en ligne

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

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

Les uploads 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 intactes. Dans un terminal interactif, elle propose au lieu du cela le flux de build native de l'éditeur Capgo ; refuser échoue. (Ne peut pas être combiné avec --ignore-metadata-check.)

Garder la livraison par version native — metadata + --auto-min-update-version

When vous faites l'envoi envoyer la construction 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 envoi et, lorsqu'un bundle nécessite de nouvelles constructions natives code, élèvez le plan d'actualisation afin que les appareils qui n'ont pas installé la construction 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

Voir La cible de version pour l'ensemble des options de ciblage.

La cible de version

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

Les retours en arrière

Rétablissez un canal à la dernière build compatible si un ensemble de fichiers incompatibles est sorti.

Mises à jour de type

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

CLI: bundle

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

Continuez de la compatibilité native

Si vous utilisez Compatibilité native pour garder les mises à jour en direct en sécurité, connectez-le avec Ciblage de version pour router les bundles par version native, Rollbacks pour récupérer lorsqu'un bundle incompatibles est expédié, Mise à jour des types pour comprendre la version de canal bloquant, et le Capgo CLI référence du bundle pour les commandes de compatibilité et de releaseType.