Compatibilité native

A Capgo mise à jour live remplace votre application’s le paquet JavaScript instantanément, mais elle ne peut pas changer la partie native de votre application — les plugins __CAPGO_KEEP_0__/Cordova, les dépendances natives et la configuration de projet native qui sont compilées 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 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 : __CAPGO_KEEP_0__ 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 cela signifie pour vos utilisateurs et comment livrer des changements natives de manière sûre.

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

Les mises à jour en temps réel sont limitées aux modifications de paquets JavaScript. Si vous avez besoin d'actualiser la partie native de votre application — en ajoutant ou en supprimant un plugin, en mettant à jour __CAPGO_KEEP_1__ ou en modifiant la configuration de projet native — vous devrez soumettre une nouvelle version binaire à travers le processus de distribution habituel des magasins d'applications.

Live updates are limited to JavaScript bundle changes. If you need to update native code — adding or removing a plugin, upgrading Capacitor, or changing native project configuration — you’ll need to submit a new binary build through the usual app-store distribution process.

__CAPGO_KEEP_0__ : Capgo, (le nom de la marque est protégé, il n'est donc pas traduit) __CAPGO_KEEP_1__ : Capacitor (le nom de la marque est protégé, il n'est donc pas traduit)

Capgo peut envoyer des fichiers depuis le 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 dans cet output, expédiez-l’en tant que mise à jour live.

Utilisez une mise à jour native de l'application lorsque la modification met à jour capacitor.config.ts, la 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. Un contrôle pratique : si la modification doit mettre à jour le projet natif par npx cap sync ou npx cap copy context

ou	Ship with Capgo OTA?	ou
context	ou	context
Les modifications du package Pure-JavaScript sont encapsulées dans votre sortie web.	Oui	Le JavaScript généré fait partie du paquet web.
capacitor.config.ts les modifications	Non	Capacitor config est lu dans l'application native au moment de la construction.
Ajouter, supprimer ou mettre à jour les plugins Capacitor/Cordova	Non	Le 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 de client 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é natives s'appliquent quel que soit le plugin de client — elles comparant les dépendances natives enregistrées du bundle aux binaires installés.

Pourquoi la compatibilité native compte

Capacitor chaque application embarque deux couches :

• Le le code natif les utilisateurs l'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.

Une mise à jour en direct échange uniquement la couche JavaScript. Si ce nouveau JavaScript appelle un plugin natif ou API qui n'est pas compilé dans le code 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 précédente ne peut pas exécuter en toute sécurité un paquet construit contre les code natifs nouveaux.

Comment Capgo détecte la compatibilité

Lorsque vous téléchargez un paquet — ou que vous exécutez la vérification manuellement — Capgo compare les les packages natifs dans votre projet local (vos Capacitor/Cordova plugins et leurs versions) aux packages natifs enregistrés pour le paquet actuellement en direct sur le canal:

• Si elles correspondent, la mise à jour 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 natif — ces changements ne prennent effet qu'une fois que les utilisateurs ont installé un nouveau 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

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

Quelle est l'importance d'une mise à jour incompatible pour vos utilisateurs

Attention

Par défaut, la détection d'incompatibilité ne bloque pas l'envoi — si vous envoyez un bundle incompatible avec la nativité et que vous le définissez comme la mise en construction 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 barrage dur avec — voir --fail-on-incompatible incompatibilité Prévenir les livraisons incompatibles ci-dessous.

Sur les appareils qui fonctionnent toujours avec la version native plus ancienne, la bibliothèque native manquante code 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 une mise à jour en direct peut être en direct et livrée tout en cassant l'application pour les utilisateurs existants, et pourquoi Capgo peut vous avertir lorsque l'un des paquets incompatibles est mis en ligne.

Capgo’s retour 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.

exécute — mais ce n'est pas un substitut pour la livraison de bibliothèques natives compatibles — une incompatibilité qui plante plus tard, ou plante nativement, peut lui échapper.

Section intitulée « Comment livrer des modifications natives de manière sûre » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » » 

Lorsqu'un bundle nécessite de nouvelles mises en ligne 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 du bundle s'alignent et la mise à jour en direct fonctionne correctement.

Annulez si un bundle incohérent est déjà en ligne

Si un bundle incohérent est déjà actif sur un canal, rétablissez le canal à la dernière version compatible pour arrêter de le servir jusqu'à ce que la mise en ligne native soit disponible. Consultez Annulations.

Empêchez les livraisons incompatibles

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

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

Ajoutez la bannière à votre bundle upload Étape. Si les packages natives du bundle ne correspondent pas à la version actuellement en ligne du canal, l'upload se termine avec un code de sortie non nul et rien n'est envoyé — donc votre pipeline vous empêche de publier silencieusement une mise à jour OTA qui ne peut prendre effet qu'une fois que les utilisateurs ont installé une version native :

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

Envois 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 place du Capgo Builder la mise à niveau native au lieu ; refuser échoue. (Ne peut pas être combiné avec --ignore-metadata-check.)

Conseil

Lorsque vous intentionnellement avez besoin d'un bundle qui diffère des packages natifs en direct du canal (nouveau plugin, Capacitor mise à niveau, et ainsi de suite), ommettez --fail-on-incompatible pour cette envoi de base. Gardez la flag sur le CI OTA quotidien. Flux de travail complet du canal : Workflow de canal natif + OTA.

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

Lorsque vous faites 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, lorsque le bundle nécessite de nouvelles versions natives code, élèvez le niveau de mise à jour afin que les appareils qui n'ont pas installé la construction 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 sont Not un substitut — ils ne bloquent 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 est toujours envoyée. Utilisez 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-versionCompatibilité de version

pour l'ensemble des options de ciblage. Lié Sécurité native + flux OTA

Canaux de développement/production, quand conserver

Native + flux OTA

Native + flux OTA --fail-on-incompatibleNative + flux OTA

Auto OTA ou Native

Fil bundle releaseType à l'intérieur GitHub Actions ou GitLab afin que CI sélectionne la mise à jour en direct par rapport à Capgo Build.

Visibilité de la Version

context

Delivrez uniquement des ensembles compatibles à l'aide de canaux, de règles semver et de la stratégie de métadonnées.

Rollbacks

Revenir à un canal vers la dernière version compatible si un ensemble incompatible est mis en ligne.

Types de Mises à Jour

CLI: bundle

__CAPGO_KEEP_0__: ensemble

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

Si vous utilisez Compatibilité native pour garder les mises à jour en direct en sécurité, connectez-l’à Version ciblée context : Page/zone : page de marketing de solutions Capgo. Rôle : Titre de section ou de page. Voir dans : page solutions/version-targeting.astro. Clé de message `solutions_version_targeting_title` (Titre de version de solutions). | Page/zone : page de marketing de solutions Capgo. Rôle : Étiquette de navigation ou élément de menu court. Voir dans : page solutions/version-targeting.astro. Clé de message `solutions_version_targeting` (Version de solutions ciblée). pour router les bundles par version native, Rollbacks pour récupérer lorsqu'un bundle incompatibles est expédié, Types d'actualisations Capgo CLI bundle reference __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ référence de bundle pour la compatibilité et les commandes releaseType.