Compatibilità nativa

Una Capgo live update sostituisce la tua app' pacchetto JavaScript istantaneamente, ma non può cambiare la 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 native-incompatible: Capgo può ancora fornirlo, ma potrebbe bloccarsi o comportarsi in modo anomalo su dispositivi che ancora utilizzano 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

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.

TLDR: OTA o nativo?

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

Usa una versione nativa del'app quando un cambiamento aggiorna capacitor.config.ts, la configurazione del plugin memorizzata nel 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 che i dispositivi installati possano utilizzarlo, trattalo come nativo.

Cambiamento	Invia con Capgo OTA?	Perché
HTML, CSS, app JavaScript, immagini, font e altri asset di costruzione web	Sì	Sono caricati dal bundle web in esecuzione.
I pacchetti Pure-JavaScript vengono modificati e bundlat nel tuo output web	Sì	Il JavaScript generato fa parte del bundle web.
capacitor.config.ts Modifiche	No	Capacitor la configurazione viene letta nell'app nativa al tempo di costruzione.
Aggiunta, rimozione o aggiornamento dei plugin Capacitor/Cordova	No	Il binario nativo installato deve contenere il code nativo corrispondente.
File di progetto iOS o Android modificati	No	Gli utenti esistenti necessitano di un nuovo binario dai negozi.

Plugin per client da pila

Capgo fornisce client di aggiornamento dedicati per ogni runtime ibrido:

Plugin	Usa quando
@capgo/capacitor-updater	Capacitor app iOS/Android
@capgo/cordova-updater	App di Cordova iOS 7+ / Android 13+
@capgo/electron-updater	App 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

Tutti gli Capacitor vengono distribuiti in due layer:

• La binario nativo che 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 via aria.

Un live update sostituisce solo il layer JavaScript. Se quel nuovo JavaScript chiama un plugin nativo o API che non è stato compilato nel binario installato, la chiamata fallisce all'esecuzione — il che può far bloccare l'applicazione o rompere silenziosamente una funzionalità. In poche parole: Capgo non può aggiornare il code nativo, 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à

When si carica un bundle — o si esegue il controllo manualmente — Capgo confronta i pacchetti nativi Pacchetti nativi nei progetti locali (i tuoi Capacitor/plugin di Cordova e le loro versioni) con i pacchetti nativi registrati per il bundle attualmente in distribuzione sul canale:

• Se corrispondono, il cambiamento è esclusivamente JavaScript e è sicuro per essere inviato via aria.
• Se è stato aggiunto, eliminato o modificato il plugin, il bundle è incompatibile con il 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

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

Consiglio

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

Ottieni un verdetto leggibile da macchina (CI)

Per i flussi di lavoro, bundle releaseType collapsa il controllo in una parola sola:

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

Controlla la tua pipeline di rilascio su questo: invia un live update quando stampa OTAe attiva una compilazione nativa quando stampa native.

Cosa significa un aggiornamento incompatibile per i tuoi utenti

Attenzione

Di default, il rilevamento dell'incompatibilità non non blocca l'upload — se carichi un bundle non compatibile con il nativo e lo stabilisci come build attiva del canale, Capgo conseguirà consegnarlo a dispositivi su quel canale. (Puoi trasformare questo in una soglia dura con) --fail-on-incompatible vedi Prevenire le consegne incompatibili di seguito.)

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 verifiche, ma non è un sostituto per la distribuzione di applicazioni native compatibili code.

Come spedire modifiche native in modo sicuro

Pubblica una nuova build nativa (la vera soluzione)

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 live update funziona correttamente.

Ripristina se un bundle incompatibile è già live

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

Prevenire le consegne incompatibili

Due guardiani complementari, entrambi dei quali esaminano effettivamente i pacchetti nativi:

Fallisce 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 live 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 potrà 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 una finestra del terminale interattiva offre al suo posto il flusso di costruzione nativa del Capgo Builder; rifiutando fallisce. (Non può essere combinato con --ignore-metadata-check.)

Tip

Quando tu intenzionalmente ha bisogno di un bundle che si differenzia dai pacchetti nativi live del canale (nuova estensione, Capacitor aggiornamento, e così via) --fail-on-incompatible per quella caricata di base. Mantieni la bandiera ogni giorno CI. Flusso di lavoro completo del canale: Flusso di lavoro del canale nativo + OTA.

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

Quando tu fai invia la costruzione nativa e il bundle insieme, metti il canale sulla metadata strategy e caricamento con --auto-min-update-version. Capgo esegue il controllo di compatibilità su ogni caricamento e, quando un bundle ha bisogno di nuovi code nativi, alza il piano di aggiornamento in modo che i dispositivi che non hanno installato la costruzione nativa 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-numero come --disable-auto-update major sono non un sostituto — bloccano solo i salti di versione e non esaminano mai il codice nativo code, quindi una modifica nativa inviata in una versione minore o di correzione va comunque in esecuzione. Utilizzare --fail-on-incompatible o --auto-min-update-versionControlla i tuoi pacchetti nativi.

Vedi Targeting di Versione per il set completo di opzioni di targeting.

Related

Flusso nativo + OTA

Canali Dev/produzione, quando conservare --fail-on-incompatible, e come spingare una linea di base nativa intenzionale.

Auto OTA o Nativo

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

Target di Versione

Distribuire solo pacchetti compatibili utilizzando i canali, le regole semver e la strategia dei metadati.

Rollbacks

Ritorna un canale al build compatibile precedente se un bundle incompatibile è stato pubblicato.

Tipi di Aggiornamento

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

CLI: pacchetto

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

Continua da compatibilità nativa

Se stai utilizzando Compatibilità nativa per mantenere aggiornate le live updates, connettile con Target di versione per route bundle tramite versione nativa, Rollbacks per indirizzare i pacchetti in base alla versione nativa, Tipi di Aggiornamento per comprendere la versione del canale di blocco, e il Capgo CLI riferimento al pacchetto per i comandi di compatibilità e releaseType.