Compatibilité native

A Capgo mise à jour en temps réel 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 cours d'exécution de 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.

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 changeant la configuration de projet native — vous devrez soumettre une nouvelle build binaire via 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.

Note : __CAPGO_KEEP_0__ ne peut pas modifier la partie native de votre application. Si vous avez besoin d'actualiser la partie native, vous devrez soumettre une nouvelle build binaire via le processus de distribution habituel des magasins d'applications.

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 bundlés dans cet output, envoyez-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. Une vérification pratique : si la modification doit mettre à jour le projet natif à travers 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 à l'étape de construction.
Ajouter, supprimer ou mettre à jour les plugins Capacitor / Cordova	Non	Le binôme 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 binôme 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 bureau

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 en deux couches :

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

Une mise à jour en temps réel é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 faille à 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 code natifs, donc un appareil exécutant la version native ancienne 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 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 natif — ces changements ne prennent effet qu'une fois que les utilisateurs installent un nouveau binaire natif.

Vérifiez depuis le 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 le contrôl’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

Gardez votre pipeline de mise en production sur ceci : envoyez une mise à jour live lorsque cela imprime OTAet déclenchez une construction native lorsque cela imprime native.

Quelle est la signification 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 plateforme native et que vous le définissez comme la 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 aux appareils sur ce canal. (Vous pouvez transformer cela en une porte de sécurité avec — voir --fail-on-incompatible pagePath Prévenir les livraisons incompatibles ci-dessous.)

Sur les appareils qui fonctionnent toujours avec la binaire native plus ancienne, le code manquant peut provoquer des plantages ou des fonctionnalités endommagées — même si l'actualisation a été téléchargée et appliquée « avec succès ». C'est pourquoi une mise à jour live peut être live et livrée 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 peut effectuer un rôle de roulement 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.

mais ce n'est pas un substitut à la livraison de __CAPGO_KEEP_0__ native compatible — un désaccord qui plante plus tard, ou plante nativement, peut lui échapper.

Titre de la section « Comment livrer des changements 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 à 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 mise en ligne compatible pour arrêter de le servir jusqu'à ce que la mise en ligne native soit disponible. Consultez Les 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 inaltérés. Dans un terminal interactif, il propose au lieu de cela la Capgo Builder flux de construction native au lieu de cela ; 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 natives en direct du canal (nouveau plugin, Capacitor mise à niveau, et ainsi de suite), omettez --fail-on-incompatible pour cette envoi de base. Gardez la bannière sur le CI OTA quotidien. Flux de workflow 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 téléchargez avec --auto-min-update-version.Capgo exécute la vérification de compatibilité à chaque téléchargement 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 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 continue 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-versionLa cible de version

pour l'ensemble des options de ciblage. Lié Sous-section intitulée « Lié »

Flux natif + OTA

, et comment déployer une base native intentionnelle.

Section intitulée « Native + OTA Workflow » --fail-on-incompatibleSection intitulée « Related »

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.

Ciblage de Version

context

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

Rollbacks

Rétablir un canal à la dernière build compatible si un ensemble incompatible est sorti.

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 des solutions Capgo. Rôle : En-tête de section ou de page. Vu dans : page solutions/version-targeting.astro. Message clé `solutions_version_targeting_title` (Titre des solutions de version ciblée). | Page/zone : Page de marketing des solutions Capgo. Rôle : Étiquette de navigation ou élément de menu court. Vu dans : page solutions/version-targeting.astro. Message clé `solutions_version_targeting` (Solutions de version ciblée). pour router les bundles par version native, Rollbacks pour récupérer lorsqu'un bundle incompatibles est expédié, Types de mise à jour Capgo CLI bundle reference __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ référence du bundle pour la compatibilité et les commandes releaseType.