Compatibilità Nativa

Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.

Una Capgo aggiornamento in tempo reale sostituisce il pacchetto JavaScript dell'applicazione istantaneamente, ma non può modificare la parte nativa dell'applicazione — i plugin Cordova nativi, le dipendenze native e la configurazione del progetto nativo che sono compilate nel binario installato. Quando un nuovo pacchetto richiede __CAPGO_KEEP_1__ nativi che il binario installato non ha, il pacchetto è incompatibile con il sistema operativo 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 __CAPGO_KEEP_1__: 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.

TLDR: OTA o nativo?

Capgo può inviare file dal tuo folder di generazione del build web. Se il cambiamento influisce solo su HTML, CSS, JavaScript, asset o pacchetti di JavaScript puro raccolti in quel output, invialo come aggiornamento in tempo reale.

Usa una versione di rilascio dell'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 che i dispositivi installati possano utilizzarlo, trattalo come nativo.

Modifica	Consegnare con Capgo OTA?	Perché
HTML, CSS, app JavaScript, immagini, font e altri asset di costruzione web	Sì	Sono caricati dal bundle web in esecuzione.
Modifiche del pacchetto Pure-JavaScript incorporate nel tuo output web	Sì	Il JavaScript generato fa parte del bundle web.
`capacitor.config.ts` modifiche	No	Capacitor config viene letta nell'app nativa al tempo di costruzione.
Aggiungere, rimuovere o aggiornare i plugin Capacitor/Cordova	No	Il binario nativo installato deve contenere il matching nativo code.
Modifiche al 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 applicazioni iOS/Android
`@capgo/cordova-updater`	Applicazioni iOS 7+ / Android 13+
`@capgo/electron-updater`	Applicazioni desktop di Electron

Le verifiche di compatibilità nativa si applicano indipendentemente dal plugin del client — confrontano le dipendenze native registrate del pacchetto con il binario installato.

Perché la compatibilità nativa è importante

Ogni applicazione Capacitor viene distribuita in due layer:

Il binario nativo users install from the App Store / Play Store. It contains Capacitor, your native plugins, and native configuration.
Contiene __CAPGO_KEEP_0__, i tuoi plugin nativi e la configurazione nativa. Il (your web app) that Capgo can update over the air.

A l'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 — il che può far crashare l'applicazione o rompere silenziosamente una funzionalità. In poche parole: Capgo non può aggiornare i plugin nativi, code, quindi un dispositivo che esegue la versione nativa vecchia non può eseguire in sicurezza un pacchetto che è stato costruito contro nuovi plugin nativi code.

Come Capgo rileva la compatibilità

Quando carichi un pacchetto — 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 linea sul canale:

Se corrispondono, la modifica è JavaScript-only e è sicuro inviarla via aria.
Se è stato aggiunto, eliminato o modificato il versione di un plugin, il pacchetto è incompatibile con il plugin nativo — quelle modifiche hanno effetto solo quando gli utenti installano un nuovo binario nativo.

Verifica 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

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 una compilazione nativa quando lo stampa native.

Cosa significa per i tuoi utenti un aggiornamento incompatibile

Prevenire le consegne incompatibili su dispositivi che ancora utilizzano il 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.

la mancanza di Capgo nativo 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 bundle incompatibile va 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.

Come inviare modifiche native in modo sicuro

Pubblica un nuovo build nativo (la soluzione reale)

Quando un bundle richiede nuovi code nativi, costruisci e invia un nuovo binario sullo Store App / Play (o ricostruisci con Capgo Cloud Build). Una volta che gli utenti aggiornano il binario, le dipendenze native del bundle si allineano e l'aggiornamento in tempo reale funziona correttamente.

Ripristina se un bundle incompatibile è già attivo

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 il build nativo non è disponibile. Vedi Ripristini.

Prevenire le consegne incompatibili

Due guardiani complementari, entrambi i quali esaminano effettivamente i 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 — 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

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

Regola la consegna in base alla versione nativa — metadata + --auto-min-update-version

When si esegue il build nativo e il bundle insieme, impostare il canale sulla strategia e caricare con quando si esegue l'upload, __CAPGO_KEEP_0__ esegue il controllo di compatibilità su ogni upload e, quando un bundle richiede nuove __CAPGO_KEEP_1__, solleva il piano di aggiornamento in modo che i dispositivi che non hanno installato il build nativo corrispondente non lo ricevano: Fermata del terminale metadata Copiare nel portapenne --auto-min-update-version. Capgo runs the compatibility check on every upload and, when a bundle needs new native code, raises the update floor so devices that haven’t installed the matching native build don’t receive it:

# 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

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

Target di Versione

Inviare solo bundle compatibili utilizzando canali, regole di semver e la strategia di metadati.

Rollback

Revertire un canale alla versione compatibile più recente se un bundle incompatibile è stato pubblicato.

Tipi di Aggiornamento

Come funzionano la programmazione del tempo, le condizioni di ritardo e il blocco di versione insieme.

CLI: bundle

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

Continua da qui per la compatibilità nativa

Se stai utilizzando Compatibilità Nativa per mantenere gli aggiornamenti live sicuri, connettilo con Target di Versione per indirizzare i pacchetti in base alla versione nativa, Rollback per recuperare quando un bundle incompatibile viene inviato, Aggiornamenti di tipo per comprendere la versione del canale che blocca e il Capgo CLI riferimento al bundle per i comandi di compatibilità e releaseType.