Compatibilità Nativa

Una Capgo aggiornamento in tempo reale sostituisce il bundle JavaScript dell'applicazione Installazione, sincronizzazione e guida del codice sorgente da un solo prompt copiabile. istantaneamente, ma non può cambiare la nativo parte del tuo app — i plugin Capacitor/Cordova, le dipendenze native e la configurazione del progetto native che sono compilate nel file binario installato. Quando un nuovo bundle aspetta code native che il file binario installato non ha, il bundle è incompatibile con il nativo: Capgo può ancora consegnarlo, ma potrebbe bloccarsi o comportarsi in modo anomalo su dispositivi che ancora eseguono la versione più vecchia del build nativo.

Questa pagina spiega come Capgo rileva la compatibilità nativa, cosa significa un aggiornamento incompatibile per i tuoi utenti e come inviare cambiamenti nativi in modo sicuro.

Nota

Gli aggiornamenti in tempo reale sono limitati ai cambiamenti del bundle JavaScript. Se hai bisogno di aggiornare code native — aggiungendo o rimuovendo un plugin, aggiornando Capacitor, o cambiando la configurazione del progetto nativo — dovrai inviare un nuovo file binario attraverso il processo di distribuzione abituale delle app-store.

Riassunto: OTA o nativo?

Capgo può inviare file dal tuo cartella di output generato web. Se il cambiamento riguarda solo l'HTML, CSS, JavaScript, asset o pacchetti JavaScript puri che sono stati bundlat in quel output, invialo come aggiornamento in tempo reale.

Usa una versione di app nativa quando un cambiamento aggiorna capacitor.config.tsla configurazione del plugin memorizzata in Capacitor config, plugin nativi o dipendenze, Capacitor stesso, o file del progetto iOS/Android. npx cap sync Una verifica pratica: se il cambiamento deve aggiornare il progetto nativo attraverso npx cap copy o

prima che i dispositivi installati possano utilizzarlo, trattalo come nativo.	Ship with Capgo OTA?	Consegnare con __CAPGO_KEEP_0__ OTA?
Perché	HTML, CSS, JavaScript dell'applicazione, immagini, font e altri asset di costruzione web	Sì
Sono caricati dal bundle web in esecuzione.	Modifiche di pacchetti Pure-JavaScript raccolte nella tua output web	Il JavaScript generato fa parte del bundle web.
capacitor.config.ts Modifiche	No	Il Capacitor config viene letto nell'app nativa al momento della compilazione.
Aggiungere, rimuovere o aggiornare Capacitor/Cordova plugin	No	Il binario nativo installato deve contenere il code nativo corrispondente.
Modifiche al file di progetto iOS o Android	No	Gli utenti esistenti hanno bisogno di un nuovo binario dalle store.

Plugin client per stack

Capgo dispiega client aggiornatori 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 del client — confrontano le dipendenze native registrate del pacchetto con il binario installato.

Perché la compatibilità nativa è importante

Ogni app Capacitor viene distribuita in due layer:

• Il binario nativo gli utenti installano dall'App Store / Play Store. Contiene Capacitor, i tuoi plugin nativi, e la configurazione nativa.
• La bundle JavaScript (la tua app web) che Capgo può aggiornare in tempo reale.

Un aggiornamento in tempo reale sostituisce solo il layer JavaScript. Se quel nuovo JavaScript chiama un plugin nativo o API che non è compilato nella versione installata del binario, la chiamata fallisce all'esecuzione — il che può far bloccare l'applicazione o rompere silenziosamente una funzionalità. In poche parole: Capgo non può aggiornare i code nativi, quindi un dispositivo che esegue la versione nativa vecchia non può eseguire in sicurezza un bundle costruito contro nuovi code nativi.

Come Capgo rileva la compatibilità

Quando carichi un bundle — o esegui la verifica manualmente — Capgo confronta i pacchetti nativi in your local project (your Capacitor/Cordova plugins and their versions) against the native packages recorded for the bundle attualmente in distribuzione sul canale:

• Se corrispondono, la modifica è solo JavaScript e sicuro da spedire in rete.
• Se è stato aggiunto, eliminato o modificato il versione di un plugin, il bundle è incompatibile con il nativo — quelle modifiche 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

Il CLI stampa una tabella di ogni pacchetto nativo con la sua versione locale, la versione live 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 (utile nei log CI), e --package-json / --node-modules per puntare ai percorsi giusti in un repository monolitico.

Ottenere un verdetto leggibile da macchina (CI)

Per 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

Regola il tuo flusso di rilascio su questo: invia un aggiornamento live quando stampa OTA, e attiva una compilazione nativa quando stampa native.

What significa un aggiornamento incompatibile per i tuoi utenti

Attento

Di default, la detezione di incompatibilità non blocca l'upload — se si carica un bundle nativo-incompatibile e lo si stabilisce come build attiva per un canale, __CAPGO_KEEP_0__ lo consegnerà block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo vedere Prevenire le consegne incompatibili --fail-on-incompatible di seguito.) Prevenire le consegne incompatibili di seguito.

On dispositivi ancora in esecuzione con il binario nativo più vecchio, la mancanza di __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'app per gli utenti esistenti, e per cui __CAPGO_KEEP_1__ può avvertirti quando un pacchetto incompatibile va live. __CAPGO_KEEP_0__’s, 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 esegua, ma non è un sostituto per lo shipping di __CAPGO_KEEP_0__ nativi compatibili — un mismatch che causa un crash successivo, o un crash nativo, può sfuggire a esso. Come inviare modifiche native in modo sicuro 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.

Pubblica un nuovo build nativo (la vera soluzione)

Quando un pacchetto richiede nuovi __CAPGO_KEEP_0__ nativi, costruisci e invia un nuovo binario sullo Store App / Play (o ricostruisci con __CAPGO_KEEP_1__ Cloud Build). Una volta che gli utenti aggiornano il binario, le dipendenze native del pacchetto si allineano e l'aggiornamento live funziona correttamente.

When a bundle needs new native code, build and submit a new binary to the App Store / Play Store (or rebuild with Capgo Cloud Build). Once users update the binary, the bundle’s native dependencies line up and the live update runs correctly.

Ritorna indietro se un pacchetto incompatibile è già in linea

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

Prevenire le consegne incompatibili

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

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

Aggiungi la flag alla tua bundle upload passo. Se i pacchetti nativi del bundle non corrispondono alla versione attualmente in linea del canale, l'upload fallisce con un codice di uscita non zero e nulla viene spedito — quindi il tuo pipeline ti ferma dal pubblicare silenziosamente 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

Compatible uploads — and cases where the check can’t run (a new channel, or no remote metadata) — pass through unchanged. In an interactive terminal it offers the Capgo Builder native-build flow instead; declining fails. (Can’t be combined with --ignore-metadata-check.)

Consegna della porta da versione nativa — metadata + --auto-min-update-version

Quando tu fai spedisci la costruzione nativa e il pacchetto insieme, metti il canale sul metadata e carica con --auto-min-update-version. Capgo esegue il controllo di compatibilità su ogni caricatura e, quando un pacchetto ha bisogno di nuove costruzioni native code, solleva il piano di aggiornamento affinché i dispositivi che non hanno installato la costruzione nativa corrispondente non ricevano:

# 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 non sono un sostituto — bloccano solo i salto di versione e non esaminano mai il __CAPGO_KEEP_0__, quindi un cambiamento nativo inviato in una versione minore o di correzione viene ancora inviato. Utilizza 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 , che controllano i tuoi pacchetti nativi. --auto-min-update-versionVedi

Version Targeting per l'intero set di opzioni di targeting. Sottosezione intitolata “Relazionati”

Sezione intitolata “Relazionati”

Target di Versione

Rilascia solo bundle compatibili utilizzando canali, regole semver e la strategia di metadata.

Rollback

Reverti un canale alla versione di build più compatibile se un bundle incompatibile è stato pubblicato.

Tipi di Aggiornamento

Come funzionano la programmazione di timing, le condizioni di ritardo e la bloccatura di versione insieme.

CLI: bundle

Riferimento per la compatibilità del bundle, tipo di rilascio e opzioni di caricamento.

Continua da qui: compatibilità nativa

Se stai utilizzando Compatibilità Nativa To tenere aggiornamenti in tempo reale sicuri, connettilo con Versione di destinazione Per indirizzare i bundle in base alla versione nativa, Annullamenti Per recuperare quando un bundle incompatibile viene distribuito, Tipi di aggiornamento Per comprendere la versione del canale che blocca e il Capgo CLI riferimento al bundle Per i comandi di compatibilità e releaseType.