Compatibilità nativa

Un aggiornamento live Capgo sostituisce il pacchetto JavaScript dell'applicazione Include installazione, sincronizzazione e la guida markdown della fonte. istantaneamente, ma non può cambiare la nativo 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 incompatibile con il nativo: Capgo può ancora consegnarlo, ma potrebbe bloccarsi o comportarsi in modo anomalo sui dispositivi che ancora eseguono la versione nativa più vecchia.

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 native — dovrai inviare un nuovo build binario attraverso il processo di distribuzione abituale delle app-store.

TLDR: OTA o nativo?

Capgo può inviare file dal tuo cartello di output generato web. Se il cambiamento riguarda solo HTML, CSS, JavaScript, asset o pacchetti pure-JavaScript inclusi in quel output, invialo come aggiornamento in tempo reale.

Utilizza una versione di app nativa quando un cambiamento aggiorna capacitor.config.tsla configurazione del plugin archiviata 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, app JavaScript, immagini, font e altri asset di costruzione web	Sì
Sono caricati dal bundle web in esecuzione.	Le modifiche al pacchetto Pure-JavaScript incorporate nel tuo output web	Il JavaScript generato fa parte del bundle web.
capacitor.config.ts Modifiche	No	Il Capacitor config non 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 dai negozi.

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 comunque indipendentemente dal plugin del client — confrontano le dipendenze native registrate del pacchetto con il binario installato.

Perché la compatibilità nativa è importante

Ogni app Capacitor parte in due strati:

• 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 il nuovo JavaScript chiama un plugin nativo o API che non è compilato nella versione binaria installata, la chiamata fallisce all'esecuzione — il che può far crashare l'applicazione o rompere silenziosamente una funzionalità. In poche parole: Capgo non può aggiornare i code nativi, quindi un dispositivo che esegue la versione binaria 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 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 pacchetto è incompatibile nativo — tali 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

La CLI stampa una tabella di ogni pacchetto nativo con la sua versione locale, la versione in vita 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.

Ottieni 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

Blocca il tuo pipeline di rilascio su questo: invia un aggiornamento live quando lo stampa OTAe attiva un build nativo quando lo stampa native.

What significa un aggiornamento incompatibile per i tuoi utenti

Attenzione

Di default, la detezione dell'incompatibilità non blocca l'upload — se si carica un bundle nativo-incompatibile e si lo si stabilisce come build attiva per un canale, __CAPGO_KEEP_0__ lo 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 l'invio di un __CAPGO_KEEP_0__ nativo compatibile — 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.

Publica una nuova versione binaria nativa (la vera soluzione)

Quando un pacchetto richiede un nuovo __CAPGO_KEEP_0__ nativo, costruisci e invia una nuova versione binaria sullo Store App / Play (o ricostruisci con __CAPGO_KEEP_1__ Cloud Build). Una volta che gli utenti aggiornano la versione binaria, 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 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

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

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

Quando sei spedisce il costruito nativo e il pacchetto insieme, metti il canale sul metadata e carica con --auto-min-update-version. Capgo esegue il controllo di compatibilità su ogni caricamento e, quando un pacchetto ha bisogno di nuovi code nativi, innalza il livello di aggiornamento affinché i dispositivi che non hanno installato il costruito nativo corrispondente non lo 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 di versione come --disable-auto-update major non sono una sostituzione — bloccano solo gli scatti di versione e non esaminano mai il codice nativo __CAPGO_KEEP_0__, quindi un cambiamento nativo inviato in una versione minore o di patch viene comunque 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 “Relazionato”

Section titled “Related”

Auto OTA o Nativo

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

Versione Targeting

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

Rollbacks

Ripristina un canale alla versione compatibile precedente se un pacchetto incompatibile è stato pubblicato.

Tipi di Aggiornamento

Come funzionano la programmazione del timing, le condizioni di delay e la bloccatura della versione insieme.

CLI: pacchetto

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

Continua dall'Compatibilità Nativa

Se stai utilizzando Compatibilità nativa per mantenere aggiornate in sicurezza, connettila con Target di versione per indirizzare i bundle in base alla versione nativa, Rollback per recuperare quando un bundle incompatibile viene distribuito, Tipi di aggiornamento per comprendere il blocco di versione del canale, e il Capgo CLI riferimento del bundle per le compatibilità e i comandi di rilascio.