Compatibilità nativa

Una Capgo live update sostituisce la tua app' pacchetto JavaScript istantemente, ma non può cambiare il native 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 nativo: Capgo può ancora consegnarlo, ma potrebbe bloccarsi o comportarsi in modo anomalo su 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 a modifiche al bundle JavaScript. Se hai bisogno di aggiornare code nativo — aggiungendo o rimuovendo un plugin, aggiornando Capacitor o modificando la configurazione del progetto nativo — dovrai inviare un nuovo file binario attraverso il processo di distribuzione abituale delle app-store.

TLDR: OTA o nativo?

Capgo può inviare file dal tuo folder di output web generato. Se il cambiamento influisce solo su HTML, CSS, JavaScript, asset o pacchetti di JavaScript puri inclusi in quel output, invialo come live update.

Usa un rilascio di app nativa quando un cambiamento aggiorna capacitor.config.ts, la configurazione del plugin memorizzata in Capacitor config, plugin nativi o dipendenze, Capacitor stesso o file del progetto iOS/Android. Un controllo pratico: se il cambiamento deve aggiornare il progetto nativo attraverso npx cap sync o npx cap copy prima di installare i dispositivi possono utilizzarlo come nativo.

Cambia	Consegnare con Capgo OTA?	Perché
HTML, CSS, JavaScript dell'applicazione, immagini, font e altri asset di costruzione web	Sì	Sono caricati dal bundle web in esecuzione.
Modifiche al pacchetto JavaScript puro raccolte nella tua output web	Sì	Il JavaScript generato fa parte del bundle web.
capacitor.config.ts Le modifiche	No	Capacitor configura la applicazione nativa al momento della compilazione.
Aggiungere, rimuovere o aggiornare i plugin Capacitor / Cordova	No	Il binario nativo installato deve contenere il code nativo corrispondente.
Modifiche ai file del progetto iOS o Android	No	Gli utenti esistenti hanno bisogno di un nuovo binario dai negozi.

Plugin del client per pila

Capgo fornisce client di aggiornamento dedicati per ogni runtime ibrido:

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

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

Perché la compatibilità nativa è importante

Ogni Capacitor app viene distribuita in due layer:

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

Un live update sostituisce solo il layer JavaScript. Se il nuovo JavaScript chiama un plugin nativo o API che non è stato compilato nella versione binaria installata, la chiamata fallisce all'esecuzione — il che può far crashare l'app 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 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 distribuzione sul canale:

• Se corrispondono, la modifica è JavaScript-solo e sicura da inviare in modo wireless.
• Se è stato aggiunto, eliminato o modificato il versione di un plugin, il pacchetto è incompatibile con il 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 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

Tip

Aggiungi --text per sostituire gli emoji con OK/FAIL (maneggevole nei log di CI), e --package-json / --node-modules per puntare alle directory giuste in un repository unico.

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 flusso di rilascio su questo: invia un live update quando stampa OTAe attiva una costruzione nativa quando stampa native.

Cosa significa un aggiornamento incompatibile per i tuoi utenti

Attenzione

Di default, la detezione di incompatibilità non not Blocca l'upload — se si carica un bundle incompatibile nativamente e lo si stabilisce come build attiva del canale, Capgo lo conseguirà alla dispositivi su quel canale. (Puoi trasformare questo in una porta di ingresso con) --fail-on-incompatible — see Prevenire le consegne incompatibili below.)

Su dispositivi ancora in esecuzione con binario nativo più vecchio, 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() Esegue le prove, ma non è un sostituto per la distribuzione di applicazioni native compatibili code.

Come distribuire modifiche native in modo sicuro

Pubblica una nuova versione nativa (la vera soluzione)

Quando un bundle richiede nuove versioni native di 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 live update funziona correttamente.

Ripristina se un bundle incompatibile è già in linea

Se un bundle incompatibile è già attivo su un canale, ripristina il canale alla versione compatibile più recente per fermare la 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:

Fallire 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 — in modo che il tuo pipeline non pubblichi un aggiornamento OTA in silenzio che non potrà avere effetto fino a quando gli utenti non installano una versione nativa:

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

Consegne 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 costruzione nativa del Capgo Builder; rifiutare fallisce. (Non può essere combinato con --ignore-metadata-check.)

Consigli

Quando desideri intenzionalmente un bundle che differisce dai pacchetti nativi del canale (nuovo plugin, Capacitor aggiornamento, e così via), omessi --fail-on-incompatible per quella base di caricamento. Mantieni la bandiera ogni giorno CI. Flusso di lavoro completo del canale: Flusso di lavoro del canale nativo + OTA.

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

Quando desideri fa invia la costruzione nativa e il bundle insieme, metti il canale sulla metadata strategy e caricamento con --auto-min-update-versionEsegui Capgo il controllo di compatibilità su ogni caricamento e, quando un bundle richiede nuove librerie native code, solleva 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

Preavviso

Regole di versione come --disable-auto-update major non not 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 --auto-min-update-versioncontrollare le tue librerie native.

Vedi Versione di riferimento per l'intero set di opzioni di targeting.

Relazionati

Flusso di lavoro nativo + OTA

Canali di sviluppo e produzione, quando conservare --fail-on-incompatible, e come spedire una base nativa intenzionale.

Auto OTA o Nativo

Cavo bundle releaseType nel GitHub Azioni o GitLab affinché CI selezioni live update rispetto a Capgo Build.

Versione di riferimento

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

Ripristini

Ritorna a un canale al build compatibile più recente se un pacchetto incompatibile è stato pubblicato.

Tipi di Aggiornamento

Come funziona l'applicazione di condizioni di ritardo e blocco di versione insieme.

CLI: pacchetto

Riferimento per la compatibilità del pacchetto, releaseType e le opzioni di caricamento.

Continua da qui: compatibilità nativa

Se stai utilizzando Compatibilità nativa per mantenere gli aggiornamenti live sicuri, collega il Target di versione per route bundle con versione nativa, Rollbacks per recuperare quando un bundle incompatibile viene distribuito, Tipi di Aggiornamento per comprendere il blocco della versione del canale e il Capgo CLI riferimento al bundle per i comandi di compatibilità e releaseType.