Compatibilità nativa

Un Capgo live update sostituisce il bundle JavaScript istantaneamente, ma non può modificare il nativo parte della tua app — i plugin Capacitor/Cordova, le dipendenze native e la configurazione del progetto nativo che sono compilati nel binario installato. Quando un nuovo bundle richiede code nativi che il binario installato non ha, il bundle viene native-incompatible: Capgo può comunque consegnarlo, ma potrebbe causare crash o comportamenti anomali sui dispositivi che eseguono ancora la vecchia build nativa.

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

Nota

Gli aggiornamenti live sono limitati alle modifiche al bundle JavaScript. Se devi aggiornare il nativo code — aggiungendo o rimuovendo un plugin, aggiornando Capacitor o modificando la configurazione del progetto nativo — dovrai inviare una nuova build binaria tramite il normale processo di distribuzione degli store.

TLDR: OTA o nativo?

Capgo può inviare file dalla cartella della tua build web generata. Se la modifica riguarda solo HTML, CSS, JavaScript, asset o pacchetti in puro JavaScript inclusi in quell'output, pubblicalo come live update.

Usa un rilascio nativo dell'app quando una modifica aggiorna capacitor.config.ts, configurazione del plugin salvata nella config di Capacitor, plugin o dipendenze native, Capacitor stesso, o file del progetto iOS/Android. Un controllo pratico: se la modifica deve aggiornare il progetto nativo tramite npx cap sync oppure npx cap copy prima che i dispositivi installati possano utilizzarlo, trattalo come nativo.

Cambia	Pubblicare con Capgo OTA?	Perché
HTML, CSS, JavaScript dell'app, immagini, font e altri asset di build web	Sì	Vengono caricati dal web bundle a runtime.
Modifiche a pacchetti in puro JavaScript incluse nel tuo output web	Sì	Il JavaScript generato fa parte del web bundle.
capacitor.config.ts modifiche	No	La configurazione di Capacitor viene letta nell'app nativa al momento del build.
Aggiunta, rimozione o aggiornamento di plugin Capacitor/Cordova	No	Il binario nativo installato deve contenere il code nativo corrispondente.
Modifiche ai file di progetto iOS o Android	No	Gli utenti esistenti hanno bisogno di un nuovo binario dagli store.

Plugin client per stack

Capgo fornisce client updater dedicati per ogni runtime ibrido:

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

I controlli di compatibilità nativa si applicano indipendentemente dal plugin client: confrontano le dipendenze native registrate nel bundle con il binario installato.

Perché la compatibilità nativa conta

Ogni app Capacitor è distribuita in due livelli:

• Il binario nativo gli utenti la installano da App Store / Play Store. Contiene Capacitor, i tuoi plugin nativi e la configurazione nativa.
• Il bundle JavaScript (la tua web app) che Capgo può aggiornare over the air.

Un live update sostituisce solo lo strato JavaScript. Se quel nuovo JavaScript chiama un plugin nativo o un API non compilato nel binario installato, la chiamata fallisce a runtime — il che può causare un crash dell'app o rompere silenziosamente una funzionalità. In parole povere: Capgo non può aggiornare i code nativi, quindi un dispositivo con un vecchio build nativo non può eseguire in sicurezza un bundle compilato contro nuovi code nativi.

Come Capgo rileva la compatibilità

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

• Se corrispondono, la modifica riguarda solo JavaScript ed è sicura da distribuire over the air.
• Se un plugin è stato aggiunto, rimosso o ha cambiato versione, il bundle è non compatibile nativamente — quelle modifiche avranno effetto solo quando gli utenti installeranno un nuovo binario nativo.

Verifica da 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 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 le emoji con OK/FAIL (utile nei log di CI), e --package-json / --node-modules per puntare ai percorsi corretti in un monorepo.

Ottieni un esito leggibile da macchina (CI)

Per le pipeline, bundle releaseType riduce il check a una singola 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

Usalo come gate per la pipeline di release: pubblica un live update quando stampa OTA, e avvia una native build quando stampa native.

Cosa significa un aggiornamento incompatibile per i tuoi utenti

Attenzione

Di default, il rilevamento dell'incompatibilità hai blocca l'upload — se carichi un bundle incompatibile con il nativo e lo imposti come build attiva di un canale, Capgo lo distribuirà ai dispositivi di quel canale. (Puoi trasformarlo in un blocco rigido con --fail-on-incompatible — vedi Prevenire distribuzioni incompatibili qui sotto.)

Sui dispositivi che eseguono ancora il vecchio binario nativo, la mancanza del code nativo può causare crash o malfunzionamenti — anche se l'update è stato scaricato e applicato con “successo”. Ecco perché un live update può essere live e distribuito ma rompere comunque l'app per gli utenti esistenti, e perché Capgo può avvisarti quando un bundle incompatibile va live.

di Capgo rollback automatico può intercettare un errore JavaScript lanciato prima che notifyAppReady() venga eseguito, ma non sostituisce il rilascio di code nativi compatibili — un mismatch che provoca un crash in seguito, o un crash nativo, può sfuggirgli.

Come rilasciare modifiche native in sicurezza

Pubblica una nuova build nativa (la soluzione definitiva)

Quando un bundle richiede nuovi code nativi, fai la build e invia un nuovo binario all'App Store / Play Store (o ricostruisci con Capgo Cloud Build). Una volta che gli utenti aggiornano il binario, le dipendenze native del bundle si allineano e il live update funziona correttamente.

Effettua il rollback se un bundle incompatibile è già live

Se un bundle incompatibile è già attivo su un canale, ripristina il canale all'ultima build compatibile per smettere di servirlo finché la build nativa non sarà disponibile. Vedi Rollback.

Prevenire distribuzioni incompatibili

Due protezioni complementari, che ispezionano davvero i tuoi pacchetti nativi:

Fai fallire l'upload in CI — --fail-on-incompatible

Aggiungi il flag al tuo bundle upload step. Se i pacchetti nativi del bundle non corrispondono alla versione attualmente attiva del canale, l'upload fallisce con un exit code non zero e nulla viene pubblicato — così la tua pipeline ti impedisce di pubblicare silenziosamente un aggiornamento OTA che non potrà avere effetto finché gli utenti non installano una build nativa:

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

Gli upload compatibili — e i casi in cui il controllo non può essere eseguito (un nuovo canale o nessun metadato remoto) — passano invariati. In un terminale interattivo offre invece il flusso di build nativa di Capgo Builder; se rifiuti, fallisce. (Non può essere combinato con --ignore-metadata-check.)

Tip

Quando intenzionalmente hai bisogno di un bundle diverso dai pacchetti nativi live del canale (nuovo plugin, aggiornamento di Capacitor, ecc.), ometti --fail-on-incompatible per quel baseline upload. Mantieni la flag nella CI OTA quotidiana. Workflow completo del canale: Workflow Native + OTA Channel.

Controlla la consegna per versione nativa — metadata + --auto-min-update-version

Quando fai pubblica la build nativa e il bundle insieme, imposta il canale su metadata strategia e carica con --auto-min-update-version. Capgo esegue il controllo di compatibilità a ogni upload e, quando un bundle richiede nuovi code nativi, alza la soglia di aggiornamento per evitare che i dispositivi che non hanno installato la build nativa corrispondente 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

Regole sul numero di versione come --disable-auto-update major sono hai come sostituto — bloccano solo i salti di versione e non ispezionano mai i code nativi, quindi una modifica nativa in una release minor o patch viene comunque distribuita. Usa --fail-on-incompatible oppure --auto-min-update-version, che controllano i tuoi pacchetti nativi.

Vedi Targeting delle versioni per l'elenco completo delle opzioni di targeting.

Correlati

Workflow nativo + OTA

Canali dev/production, quando mantenerli --fail-on-incompatible, e come pubblicare una baseline nativa intenzionale.

Auto OTA o Native

Integra bundle releaseType in GitHub Actions o GitLab, così la CI sceglie live update o Capgo Build.

Targeting delle versioni

Consegna solo bundle compatibili utilizzando canali, regole semver e la strategia dei metadati.

Rollback

Riporta un canale all'ultima build compatibile se un bundle incompatibile è andato in produzione.

Tipi di aggiornamento

Come funzionano insieme timing di applicazione, condizioni di ritardo e blocco delle versioni.

CLI: bundle

Riferimento per la compatibilità dei bundle, releaseType e le opzioni di upload.

Continua da Compatibilità nativa

Se stai usando Compatibilità nativa per mantenere le live update sicure, collegalo con Targeting delle versioni to route bundles by native version, Rollback per recuperare quando viene pubblicato un bundle incompatibile, Tipi di aggiornamento per comprendere il blocco delle versioni dei canali e il Capgo CLI riferimento bundle per i comandi compatibility e releaseType.