Compatibilità nativa

A Capgo aggiorna automaticamente il tuo bundle JavaScript JavaScript bundle ma non può cambiare la parte nativa del tuo app — i plugin __CAPGO_KEEP_0__/Cordova, le dipendenze native e la configurazione del progetto nativo che sono stati compilati nel file binario installato. 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 distribuirlo, 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?

Capgo può inviare file dal folder di costruzione web generato. Se il cambiamento riguarda solo l'HTML, il CSS, il JavaScript, gli asset o i pacchetti di JavaScript puro inclusi in quel output, invialo come aggiornamento live.

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

prima che i dispositivi installati possano utilizzarlo, trattalo come nativo.	Ship with Capgo OTA?	Invia con __CAPGO_KEEP_0__ OTA?
Perché	HTML, CSS, JavaScript dell'app, immagini, font e altri asset di costruzione web	Sì
Pacchetti di modifica JavaScript puri inclusi nella tua output web	Sì	Il JavaScript generato fa parte del pacchetto web.
capacitor.config.ts modifiche	No	La configurazione Capacitor viene letta nell'app nativa al momento della compilazione.
Aggiungere, rimuovere o aggiornare i plugin Capacitor/Cordova	No	Il binario nativo installato deve contenere il binario nativo code 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 fornisce client di aggiornamento 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

Le 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

Tutte le Capacitor app sono distribuite in due layer:

• The il binario nativo gli utenti installano dallo Store App / Store Google. Contiene Capacitor, i tuoi plugin nativi, e la configurazione nativa.
• The il pacchetto JavaScript (la tua app web) che Capgo può aggiornare in modo wireless.

Un aggiornamento live sostituisce solo il layer JavaScript. Se il nuovo JavaScript chiama un plugin nativo o API che non è stato compilato nel binario installato, la chiamata fallisce all'esecuzione — che può far crashare l'applicazione o rompere silenziosamente una funzione. In poche parole: Capgo non può aggiornare code nativo, quindi un dispositivo che esegue la versione vecchia del binario nativo non può eseguire in modo sicuro un pacchetto costruito contro nuovi code nativi.

Come Capgo rileva la compatibilità

Quando carichi un pacchetto — o esegui la verifica manualmente — Capgo confronta le 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 diretta sul canale:

• Se corrispondono, la modifica è esclusivamente in JavaScript e è sicuro per essere inviato via aria.
• Se è stato aggiunto, rimosso o modificato il versione di un plugin, il pacchetto è incompatibile 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

La CLI stampa una tabella di ogni pacchetto nativo con la sua versione locale, la versione in diretta 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 scambiare gli emoji con OK/FAIL (utile nei log di CI), e --package-json / --node-modules per puntare alle directory giuste in un repository monolitico.

Sottosezione intitolata “Ottieni un verdetto leggibile da macchina (CI)”

collapsa il controllo in una sola parola: bundle releaseType Fermata dei comandi

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

Registra la pipeline di rilascio su questo: invia un aggiornamento live quando lo stampa OTAe attiva una compilazione nativa quando lo stampa native.

Cosa significa un aggiornamento incompatibile per i tuoi utenti

Attenzione

Di default, il rilevamento di incompatibilità non blocca l'upload — se carichi un bundle incompatibile nativo e lo imposti come build attiva del canale, __CAPGO_KEEP_0__ block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo ai dispositivi su quel canale. (Puoi trasformarlo in un gate rigido con — vedi --fail-on-incompatible — vedi Prevenire le consegne incompatibili di seguito.

Sui dispositivi che ancora eseguono il binario nativo più vecchio il componente nativo mancante __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 eppure ancora rompere l'applicazione per gli utenti esistenti, e per cui __CAPGO_KEEP_1__ può avvertirti quando un pacchetto incompatibile va live., 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() runs, but it isn’t a substitute for shipping compatible native code — a mismatch that crashes later, or crashes natively, can slip past it.

ma non è un sostituto per la consegna di un binario nativo compatibile — un mismatch che causa crash più tardi, o crash nativamente, può sfuggire a esso.

Sottosezione intitolata “Come inviare cambiamenti nativi in modo sicuro”

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 l'aggiornamento live funziona correttamente.

Ripristina se un bundle incompatibile è già live

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

Prevenire le consegne incompatibili

Due guardie complementari, entrambe delle quali verificano effettivamente i 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 live del canale, l'upload fallisce con un uscita non zero e non viene spedito nulla — 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

Carichi 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 posto il flusso di lavoro di costruzione nativa del Capgo Builder; rifiutando fallisce. (Non può essere combinato con --ignore-metadata-check.)

Suggerimento

Quando tu intenzionalmente hai bisogno di un pacchetto che differisce dai pacchetti nativi del canale in tempo reale (nuovo plugin, Capacitor aggiornamento, e così via), ometti --fail-on-incompatible per quella carica di base. Tieni il flag ogni giorno per la CI OTA. Flusso di lavoro del canale completo: Canale di lavoro nativo + OTA.

Consegna tramite versione nativa — metadata + --auto-min-update-version

Quando si fa invia la costruzione nativa e il pacchetto insieme, impostare il canale sulla metadata e caricare con --auto-min-update-version. Capgo esegue il controllo di compatibilità su ogni caricamento e, quando un pacchetto richiede una nuova costruzione nativa code, innalza il livello di aggiornamento in modo che i dispositivi che non hanno installato la costruzione 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

Attenzione

Le regole di numero di versione come --disable-auto-update major sono Not un sostituto — bloccano solo gli aggiornamenti 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. Utilizzare 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 avere l'insieme completo di opzioni di targeting. --auto-min-update-versionRelativo

Flusso di lavoro nativo + OTA Canali di sviluppo/produzione, quando mantenere , e come inviare una linea di base nativa intenzionale.

Vedere

Per avere l'insieme completo di opzioni di targeting.

Non --fail-on-incompatibleun sostituto — bloccano solo gli aggiornamenti 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. Utilizzare

Auto OTA o Nativo

Wire bundle releaseType inserisci GitHub Azioni o GitLab in modo che il CI riconosca l'aggiornamento live rispetto a Capgo Build.

Target di Versione

context":"Pagina/Area: Pagina di marketing delle soluzioni Capgo. Ruolo: Intestazione di sezione o pagina. Visualizzato in: pagina soluzioni/target-versione.astro. Chiave messaggio `solutions_version_targeting_title` (Titolo della versione delle soluzioni). | Pagina/Area: Pagina di marketing delle soluzioni Capgo. Ruolo: Etichetta breve di UI o elemento di navigazione. Visualizzato in: pagina soluzioni/target-versione.astro. Chiave messaggio `solutions_version_targeting` (Versione delle soluzioni)."

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

Rollback

Ripristina un canale alla versione di build più recente compatibile se un pacchetto incompatibile è stato pubblicato.

Tipi di Aggiornamento

CLI: bundle

__CAPGO_KEEP_0__: pacchetto

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

Se stai utilizzando Compatibilità nativa per mantenere aggiornate in sicurezza le live updates, connettile con Target di versione context Pagina/Area: Pagina di marketing delle soluzioni Capgo. Ruolo: Intestazione di sezione o pagina. Visualizzato in: pagina soluzioni/target-di-versione.astro. Chiave di messaggio `solutions_version_targeting_title` (Titolo della versione di soluzioni). | Pagina/Area: Pagina di marketing delle soluzioni Capgo. Ruolo: Etichetta di UI breve o elemento di navigazione. Visualizzato in: pagina soluzioni/target-di-versione.astro. Chiave di messaggio `solutions_version_targeting` (Target di versione delle soluzioni). per gestire i bundle in base alla versione nativa, Annullamenti per recuperare quando un bundle incompatibile viene distribuito, Capgo CLI bundle reference per comprendere il blocco di versione del canale, e il riferimento del bundle per la compatibilità e il comando releaseType.