Compatibilità nativa

A Capgo aggiorna automaticamente il tuo bundle JavaScript, il bundle JavaScript ma non può cambiare la parte nativa del tuo app — i plugin __CAPGO_KEEP_0__/Cordova, le dipendenze native e la configurazione del progetto nativo che sono stati compilati nel file binario installato. Quando un nuovo bundle richiede __CAPGO_KEEP_1__ nativi che il file binario installato non ha, il bundle è incompatibile con la parte nativa 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 Questa pagina spiega come __CAPGO_KEEP_0__ rileva la compatibilità nativa, cosa significa un aggiornamento incompatibile per i tuoi utenti e come distribuire cambiamenti nativi in modo sicuro.: Capgo can still deliver it, but it may crash or misbehave on devices that are still running the older native build.

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 o nativo?

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_1__

Capgo può inviare file dal tuo folder di costruzione web generato. Se il cambiamento riguarda solo l'HTML, il CSS, il JavaScript, gli asset o i pacchetti di JavaScript puro inclusi in quel output, invialo come aggiornamento live.

Usa una rilascio di app nativa quando un cambiamento aggiorna capacitor.config.ts, la configurazione del plugin memorizzata in Capacitor config, i plugin nativi o le dipendenze, Capacitor stesso o i file del progetto iOS/Android. Un controllo pratico: se il cambiamento deve aggiornare il progetto nativo attraverso npx cap sync o npx cap copy Page/area: Pagina di confronto delle alternative per gli aggiornamenti live di Capacitor. Ruolo: Paragrafo di marketing o legale lungo. Visto in: pagina alternatives.astro. Preservare i termini del prodotto e della marca Capgo e dei termini dei developer esattamente. Chiave di messaggio `alternatives_cta_questions` (Domande per le alternative CTA). | Pagina/area: Pagina di confronto e migrazione per Appflow. Ruolo: Paragrafo di marketing o legale lungo. Visto in: pagina ionic-appflow.astro. Preservare i termini del prodotto e della marca Capgo e dei termini dei developer esattamente. Chiave di messaggio `appflow_cta_questions` (Domande per le alternative CTA di Appflow). | Pagina/area: Pagina di confronto per Capawesome. Ruolo: Paragrafo di marketing o legale lungo. Visto in: pagina capwesome.astro. Preservare i termini del prodotto e della marca Capgo e dei termini dei developer esattamente. Chiave di messaggio `capwesome_cta_questions` (Domande per le alternative CTA di Capawesome). | Pagina/area: Pagina dei servizi di consulenza. Ruolo: Sottotitolo o didascalia di sezione. Visto in: pagina consulting.astro. Preservare i termini del prodotto e della marca Capgo e dei termini dei developer esattamente. Chiave di messaggio `consulting_faq_subtitle` (Sottotitolo FAQ dei servizi di consulenza). | Pagina/area: Pagina di confronto e migrazione per Appflow. Ruolo: Etichetta o elemento di navigazione breve. Visto in: pagina ionic-appflow.astro, pagina ionic-enterprise-plugins.astro, pagina solutions/ionic-enterprise-plugins.astro. Chiave di messaggio `appflow_plugins_or` (Appflow Plugins o).

prima che i dispositivi installati possano utilizzarlo, trattalo come nativo.	Ship with Capgo OTA?	Invia con __CAPGO_KEEP_0__ OTA?
Perché	HTML, CSS, JavaScript dell'app, immagini, font e altri asset di costruzione web	Sì
Pacchetti JavaScript puri modificati inclusi nella tua output web	Sì	Il JavaScript generato fa parte del pacchetto web.
capacitor.config.ts modifiche	No	La configurazione Capacitor viene letta nell'app nativa al momento della compilazione.
Aggiungere, rimuovere o aggiornare Capacitor / plugin Cordova	No	L'installato binario nativo deve contenere il matching nativo code.
Modifiche al file di progetto iOS o Android	No	Gli utenti esistenti hanno bisogno di un nuovo binario dai negozi.

Plugin client per stack

Capgo fornisce client di aggiornamento dedicati per ogni runtime ibrido:

Plugin	Usa quando
@capgo/capacitor-updater	Capacitor app iOS/Android
@capgo/cordova-updater	Applicazioni iOS 7+ / Android 13+ di Cordova
@capgo/electron-updater	Applicazioni desktop di Electron

Verifiche di compatibilità native si applicano indipendentemente dal plugin client — confrontano le dipendenze native registrate del pacchetto con il binario installato.

Perché la compatibilità nativa è importante

Tutte le Capacitor app sono distribuite in due layer:

• The il binario nativo gli utenti installano dallo Store App / Store Gioco. Contiene Capacitor, i tuoi plugin nativi, e la configurazione nativa.
• The il pacchetto JavaScript (la tua app web) che Capgo può aggiornare in tempo reale.

Un aggiornamento in tempo reale sostituisce solo il layer JavaScript. Se il nuovo JavaScript chiama un plugin nativo o API che non è stato compilato nel binario installato, la chiamata fallisce all'esecuzione — il che può far crashare l'applicazione o rompere silenziosamente una funzionalità. In poche parole: Capgo non può aggiornare code nativi, quindi un dispositivo che esegue la versione binaria nativa vecchia non può eseguire in modo sicuro un pacchetto costruito contro nuovi code nativi.

Come Capgo rileva la compatibilità

Quando carichi un pacchetto — o esegui la verifica manualmente — Capgo confronta i pacchetti nativi nel tuo progetto locale (i tuoi Capacitor/Cordova plugin e le loro versioni) con i pacchetti nativi registrati per il pacchetto attualmente in linea sul canale:

• Se corrispondono, il cambiamento è esclusivamente in JavaScript e è sicuro per essere inviato via aria.
• Se è stato aggiunto, eliminato o modificato il versione di un plugin, il pacchetto è incompatibile nativo — questi cambiamenti hanno effetto solo quando gli utenti installano un nuovo binario nativo.

Controlla dal CLI

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

CLI stampa una tabella di ogni pacchetto nativo con la sua versione locale, la versione in linea sul canale e uno stato:

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

Suggerimento

Aggiungi --text per scambiare gli emoji per OK/FAIL utili nei log dei CI, e --package-json / --node-modules per puntare alle directory giuste in un repository monolitico.

Ottieni un verdetto leggibile da macchina (CI)

Per i pipeline, bundle releaseType collapsa il controllo in una sola parola:

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

Registra la pipeline di rilascio su questo: invia un aggiornamento live quando lo stampa OTAe attiva una compilazione nativa quando lo stampa native.

Cosa significa un aggiornamento incompatibile per i tuoi utenti

Attenzione

Di default, il rilevamento dell'incompatibilità non blocca l'upload — se carichi un pacchetto nativo-incompatibile e lo imposti come build attiva del canale, __CAPGO_KEEP_0__ block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo a dispositivi su quel canale. (Puoi trasformarlo in un gate rigido con — vedi --fail-on-incompatible — vedi Prevenire le consegne incompatibili di seguito.

Sui dispositivi che ancora eseguono il binario nativo più vecchio il componente nativo mancante __CAPGO_KEEP_0__ può causare crash o funzionalità rotte — anche se l'aggiornamento è stato scaricato e applicato con successo. Questo è il motivo per cui un aggiornamento live può essere live e consegnato, ma ancora rovinare l'applicazione per gli utenti esistenti, e per cui __CAPGO_KEEP_1__ può avvertirvi quando un pacchetto incompatibile va live., 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 automatico può catturare un errore JavaScript lanciato prima 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.

esegue

Come inviare modifiche native in modo sicuro. Sezione intitolata “Come inviare modifiche native in modo sicuro”

Quando un bundle richiede nuove code, costruisci e invia una nuova versione binaria su App Store / Play Store (o ricostruisci con Capgo Cloud Build). Una volta che gli utenti aggiornano la versione binaria, le dipendenze native del bundle si allineano e l'aggiornamento live funziona correttamente.

Ripristina se un bundle incompatibile è già live

Se un bundle incompatibile è già attivo su un canale, ripristina il canale alla versione compatibile più recente per fermare la sua distribuzione fino a quando non è disponibile una nuova build nativa. Vedi Ripristini.

Prevenire le consegne incompatibili

Due guardiani complementari, entrambi dei quali effettuano effettivamente l'ispezione dei tuoi pacchetti nativi:

Falli l'upload in CI — --fail-on-incompatible

Aggiungi la flag alla tua bundle upload Se i pacchetti nativi del bundle non corrispondono alla versione attualmente live del canale, l'upload fallisce con un codice di uscita non nullo e non viene spedito nulla — quindi il tuo pipeline ti impedisce di pubblicare in modo silenzioso un aggiornamento OTA che non può avere effetto fino a quando gli utenti non installano una versione nativa:

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

Caricamenti compatibili — e casi in cui il controllo non può essere eseguito (un nuovo canale, o nessuna metadata remota) — passano invariati. In un terminale interattivo offre al suo posto il flusso di lavoro di costruzione nativa del Capgo Builder; rifiutare fallisce. (Non può essere combinato con --ignore-metadata-check.)

Consiglio

Quando tu intenzionalmente hai bisogno di un pacchetto che differisca dai pacchetti nativi del canale (nuovo plugin, Capacitor aggiornamento, e così via), ometti --fail-on-incompatible per quel caricamento di base. Mantieni la flag ogni giorno per il CI OTA. Flusso di lavoro del canale completo: Flusso di lavoro del canale nativo + OTA.

Consegna tramite versione nativa — metadata + --auto-min-update-version

Quando si fa si spedisce la versione nativa e il pacchetto insieme, impostare il canale sulla metadata e caricare con --auto-min-update-version . Capgo esegue il controllo di compatibilità su ogni caricamento e, quando un pacchetto richiede una nuova versione nativa code, innalza il livello di aggiornamento in modo che i dispositivi che non hanno installato la versione nativa corrispondente non ricevano l'aggiornamento:

# 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

Attenzione

Le regole per il numero di versione come --disable-auto-update major sono Not un sostituto — bloccano solo gli aggiornamenti di versione e non esaminano mai il codice nativo __CAPGO_KEEP_0__, quindi un cambiamento nativo inviato in una versione minore o di patch continua a essere inviato. Utilizzare 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 Per il set completo di opzioni di targeting. --auto-min-update-versionRelazionato

Flusso di lavoro nativo + OTA Canali di sviluppo/produzione, quando conservare , e come inviare una linea di base nativa intenzionale.

Vedere

Per il set completo di opzioni di targeting.

Non un sostituto — bloccano solo gli aggiornamenti di versione e non esaminano mai il codice nativo __CAPGO_KEEP_0__, quindi un cambiamento nativo inviato in una versione minore o di patch continua a essere inviato. Utilizzare --fail-on-incompatibleo

Auto OTA o Nativo o Nativo

Filamento bundle releaseType entro GitHub Azioni o GitLab in modo che CI riconosca l'aggiornamento in tempo reale rispetto a Capgo Costruzione.

Target di Versione

context

Consegna solo pacchetti compatibili utilizzando canali, regole semver e la strategia di metadati.

Rollback

Ripristina un canale alla versione costruttiva più recente compatibile se un pacchetto incompatibile è stato pubblicato.

Tipi di Aggiornamento

CLI: bundle

__CAPGO_KEEP_0__: pacchetto

Riferimento per la compatibilità del pacchetto, il tipo di rilascio e le opzioni di caricamento.

Se stai utilizzando Compatibilità nativa per mantenere aggiornate in sicurezza le live updates, connettile con Target di versione context per indirizzare i bundle in base alla versione nativa, Annullamenti per recuperare quando un bundle incompatibile viene rilasciato, Tipi di aggiornamento Capgo CLI bundle reference __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ riferimento al bundle per la compatibilità e i comandi releaseType