Compatibilità Nativa

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 stati compilati 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 Sync: Capgo can still deliver it, but it may crash or misbehave on devices that are still running the older native build.

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

Le aggiornamenti in tempo reale sono limitati ai cambiamenti del pacchetto JavaScript. Se hai bisogno di aggiornare code nativo — aggiungendo o rimuovendo un plugin, aggiornando Capacitor, o cambiando la configurazione del progetto nativo — dovrai inviare un nuovo build binario attraverso il processo di distribuzione dell'app-store.

Perché la compatibilità nativa è importante

Ogni app Capacitor 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 pacchetto JavaScript (la tua app web) che Capgo può aggiornare in tempo reale.

Un aggiornamento in tempo reale 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 bloccare 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 plugin nativi nel tuo progetto locale (i tuoi Capacitor/Cordova plugin e le loro versioni) con i plugin nativi registrati per il pacchetto attualmente disponibili sul canale:

• Se corrispondono, il cambiamento è JavaScript-only e safeto inviare in tempo reale.
• Se è stato aggiunto, eliminato o modificato il versione di un plugin, il pacchetto è incompatibile con il plugin 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

Il 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

Suggerimento

Aggiungi --text per sostituire gli emoji con OK/FAIL (utile nei log dei CI), e --package-json / --node-modules per indicare le directory giuste in un repository unico.

Ottieni un verdetto leggibile da macchina (CI)

Per le 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

Regola il tuo pipeline di rilascio su questo: invia un aggiornamento live quando lo stampa OTA, e attiva una compilazione nativa quando lo stampa native.

Cosa significa per i tuoi utenti un aggiornamento incompatibile

Attenzione

Di default, la detezione di incompatibilità non blocca l'upload — se si carica un bundle nativo-incompatibile e lo si stabilisce 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 di quel canale. (Si può trasformare questo in un gate duro con — vedere --fail-on-incompatible Prevenire le consegne incompatibili di seguito.) Su dispositivi ancora in esecuzione del binario nativo più vecchio

, la mancante nativa __CAPGO_KEEP_0__ può causare crash o funzionalità rotte — anche se l'aggiornamento scaricato e applicato è stato “eseguito 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ò avvertirvi quando un bundle incompatibile va live. Detecting incompatibilityDetecting incompatibility does not block the upload by default — if you upload a native-incompatible bundle and set it as a channel’s active build, code will deliver it to devices on that channel. (You can turn this into a hard gate with — see Prevent incompatible deliveries below.) On devices still running the older native binary, 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. Prevent incompatible deliveries Prevent incompatible deliveries by setting the incompatibility detection to block the upload. This will prevent the delivery of native-incompatible bundles to devices on the channel. Incompatibility detection Incompatibility detection is used to prevent the delivery of native-incompatible bundles to devices on the channel. This is done by setting the incompatibility detection to block the upload. Incompatibility detection does not block the upload by default — if you upload a native-incompatible bundle and set it as a channel’s active build, code will deliver it to devices on that channel. (You can turn this into a hard gate with — see Prevent incompatible deliveries below.) On devices still running the older native binary, 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() funziona, ma non è un sostituto per la distribuzione di una versione nativa compatibile di code — una disallineamento che può causare un crash successivo, o può causare un crash nativo, può sfuggire a questo.

Come distribuire cambiamenti nativi in modo sicuro

Pubblica una nuova versione nativa (la soluzione reale)

Quando un bundle richiede nuove code native, 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 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 precedente per fermare la distribuzione fino a quando non è disponibile la versione nativa. Vedi Ripristini.

Prevenire consegne incompatibili

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

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 costruttore Capgo; rifiutando fallisce. (Non può essere combinato con) --ignore-metadata-check.)

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

Quando si fa invia la versione nativa e il bundle 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 bundle richiede nuove versioni native code, solleva il piano 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

Attenzione

Regole di versione-numero come --disable-auto-update major sono non è un sostituto — bloccano solo gli aggiornamenti di versione e non esaminano mai il codice nativo __CAPGO_KEEP_0__, quindi una modifica nativa inviata in una versione minore o di patch viene comunque inviata. Utilizza 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 , che controllano i tuoi pacchetti nativi. --auto-min-update-versionVedi

Versione di destinazione per l'intero set di opzioni di destinazione. Sezione correlata titolata “Correlata”

Versione di destinazione

Rollback

Ripristino

Versione di destinazione

Ripristina un canale alla versione costruttiva più compatibile se un pacchetto incompatibile è stato pubblicato.

Aggiorna i tipi

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

CLI: pacchetto

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

Continua da qui: compatibilità nativa

Se stai utilizzando Compatibilità nativa per mantenere aggiornate in sicurezza le applicazioni, connettila con Target di versione per indirizzare i pacchetti in base alla versione nativa, Ripristini per recuperare quando un bundle incompatibile viene distribuito, Tipi di Aggiornamento per comprendere la versione bloccante del canale, e il Capgo CLI riferimento al bundle per i comandi di compatibilità e releaseType.