Comportamento dell'Aggiornamento

Quando rilasciate un aggiornamento per il vostro Capgo app, probabilmente desiderate che i vostri utenti ricevano quell'aggiornamento il prima possibile. Ma non volete anche interrompere la loro esperienza obbligandoli a attendere il download o a riavviare l'applicazione nel mezzo di una sessione.

L'aggiornamento Capgo è progettato per bilanciare la consegna degli aggiornamenti velocemente e minimizzare la distruzione per i vostri utenti.

Ciclo di Aggiornamento Predefinito

Di default, ecco come Capgo gestisce gli aggiornamenti degli app:

1. All'avvio dell'applicazione, il plugin Capgo controlla se è disponibile un nuovo aggiornamento.

2. Se viene trovato un aggiornamento, viene scaricato in background mentre l'utente continua ad utilizzare la versione corrente dell'applicazione.

3. Una volta completato il download, Capgo attende che l'utente chiuda l'applicazione o la uccida completamente.

4. Quando l'utente avvia nuovamente l'applicazione, sarà in grado di eseguire la versione aggiornata.

Questo flusso garantisce che gli utenti stiano sempre utilizzando la versione più aggiornata della tua app, senza mai essere interrotti da promemoria di aggiornamento o costretti a attendere i download.

Suggerimento

Capgo controlla anche gli aggiornamenti quando l'app si ripristina dallo stato di background, quindi gli utenti riceveranno gli aggiornamenti anche se non chiudono completamente l'app.

Perché Questo Approccio?

L'applicazione degli aggiornamenti su un evento di background o di chiusura ha alcuni benefici chiave per l'esperienza utente:

• Gli utenti non sono interrotti da promemoria di aggiornamento o costretti a attendere i download in mezzo a una sessione.

• Gli aggiornamenti vengono applicati in modo trasparente tra le sessioni, quindi l'esperienza di avvio dell'app è sempre fresca.

• Puoi distribuire gli aggiornamenti frequentemente senza preoccuparti di interrompere gli utenti attivi.

Il principale svantaggio è che se un utente mette in background e ripristina rapidamente la tua app, potrebbe perdere lo stato non salvato dal momento in cui l'aggiornamento è stato applicato tra quelle azioni.

Per mitigare questo, raccomandiamo:

• Salvare lo stato frequentemente e ripristinarlo con grazia quando l'app si riavvia.

• Evitare aggiornamenti molto frequenti che modificano parti grandi dello stato dell'app.

• Considerare la personalizzazione del comportamento di aggiornamento per flussi sensibili (vedi di seguito).

Personalizzare Quando gli Aggiornamenti Sono Applicati

In alcuni casi, potresti voler avere più controllo sul momento esatto in cui viene applicato l'aggiornamento. Ad esempio, potresti voler assicurarti che l'utente completi un flusso in corso prima di aggiornare, o coordinare un aggiornamento dell'app con un cambiamento server-side.

Capgo fornisce una setDelay funzione che ti consente di specificare le condizioni che devono essere soddisfatte prima di installare l'aggiornamento:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

await CapacitorUpdater.setMultiDelay({
  delayConditions: [
    {
      kind: 'date',
      value: '2023-06-01T00:00:00.000Z',
    },
    {
      kind: 'background',
      value: '60000',
    },
  ],
});

Questo esempio ritarderebbe l'installazione di un aggiornamento fino a dopo il 1 giugno 2023 E l'app è stata messa in background per almeno 60 secondi.

Il ritardo disponibile è:

• date: Aspetta fino a una data/ora specifica per applicare l'aggiornamento.
• background: Aspetta un minimo di durata dopo che l'app è stata messa in background per applicare l'aggiornamento.
• nativeVersion: Aspetta per un binario nativo con una versione minima per essere installato prima di applicare l'aggiornamento.
• kill: Aspetta fino all'evento di uccisione dell'app successiva per applicare l'aggiornamento.

Potete mescolare e combinare queste condizioni per controllare esattamente quando viene installato l'aggiornamento.

Danger

Nota che la kill condizione attualmente attiva l'aggiornamento dopo l'evento di uccisione iniziale, non l'evento di background successivo come le altre condizioni. Questa incoerenza verrà risolta in una versione futura.

Applicare Aggiornamenti Subito

Per aggiornamenti critici o app con uno stato molto semplice, potreste voler applicare un aggiornamento non appena è stato scaricato, senza aspettare un evento di background o di uccisione. Capgo supporta questo tramite l'opzione di configurazione. directUpdate Applying Updates Immediately

Consigliato: utilizzare Aggiornamenti Delta (Manifesto) con Aggiornamento diretto

Quando si utilizza directUpdate noi fortemente raccomandiamo di abilitare Aggiornamenti Delta (manifesto) per ridurre i tempi di download e migliorare l'esperienza utente. Gli aggiornamenti Delta (manifesto) scaricano solo i file modificati invece dell'intero pacchetto, il che è particolarmente importante quando gli aggiornamenti vengono applicati immediatamente mentre gli utenti stanno utilizzando attivamente l'app.

Perché ciò è importante per gli Aggiornamenti diretti:

• Aggiornamenti più veloci: Scarichi più piccoli significano che gli aggiornamenti si completano rapidamente, riducendo il tempo che gli utenti vedono schermate di caricamento
• Miglior esperienza mobile: Gli utenti con reti cellulari o connessioni più lente non dovranno affrontare tempi di attesa lunghi
• Lower bandwidth usage: Solo i file modificati vengono scaricati, risparmiando dati per te e i tuoi utenti

When directUpdate è abilitato nel tuo capacitor.config, il CLI lo rileva. In ambienti non interattivi invia aggiornamenti Delta (manifesto) automaticamente, mentre in ambienti interattivi ti chiede di confermare prima di caricare. Utilizza --no-delta per forzare l'upload di un bundle completo.

To enable Delta (manifest) updates, simply use the --delta flag when uploading bundles:

npx @capgo/cli@latest bundle upload --delta

Scopri di più in Aggiornamenti (manifesto) Aggiorna la documentazione.

directUpdate è impostato nel tuo capacitor.config.ts file, non nel JavaScript code. Supporta tre valori:

• false (predefinito): Non eseguire mai gli aggiornamenti diretti (utilizzare il comportamento predefinito: scaricare all'avvio, impostare quando in background)
• 'atInstall'Aggiornamento diretto solo quando l'app è installata, aggiornata dal negozio, altrimenti agisci come se directUpdate = false
• 'onLaunch'Aggiornamento diretto solo quando l'app è installata, aggiornata dal negozio o dopo aver ucciso l'app, altrimenti agisci come se directUpdate = false
• 'always'Aggiornamento diretto in tutti i casi precedenti (app installata, aggiornata dal negozio, dopo aver ucciso l'app o dopo aver ripristinato l'app), non agire mai come se directUpdate = false
• true (deprecated): Lo stesso di 'always' per compatibilità con le versioni precedenti

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      directUpdate: 'always', // or 'atInstall' for updates only on app install/update
      autoSplashscreen: true, // NEW: Automatically handle splashscreen
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false, // Still required when using directUpdate
    },
  },
};

export default config;

Nota

E' importante notare che le nuove versioni vengono applicate solo quando l'app effettivamente controlla per loro. Di default, ciò avviene solo all'avvio dell'app o quando si torna in primo piano da background. Nota che: directUpdate non è compatibile con periodCheckDelay Con directUpdate.

abilitato, __CAPGO_KEEP_0__ applicherà immediatamente l'aggiornamento non appena il download è completo durante un controllo di aggiornamento, anche se l'utente sta utilizzando l'app attivamente. Senza il controllo periodico abilitato, ciò significa che gli aggiornamenti saranno applicati solo quando l'app inizia o torna in primo piano da background. directUpdate enabled, Capgo will immediately apply an update as soon as the download completes during an update check, even if the user is actively using the app. Without periodic checking enabled, this means updates will only be applied when the app starts or resumes from background.

è una configurazione nativa, richiede alcune ulteriori gestione nel tuo JavaScript __CAPGO_KEEP_0__. directUpdate is a native configuration, it requires some additional handling in your JavaScript code.

Quando si utilizza

, è necessario impostare directUpdatenel configurazione dello SplashScreen (come mostrato sopra) per impedire allo schermo di benvenuto di nascondersi automaticamente. Ciò assicura di avere il pieno controllo su quando lo schermo di benvenuto viene nascosto dopo la conclusione del processo di aggiornamento. launchAutoHide: false E' importante notare che le nuove versioni vengono applicate solo quando l'app effettivamente controlla per loro.

Gestione Automatica dello Splashscreen

Per rendere directUpdate più facile da utilizzare, Capgo offre autoSplashscreen un'opzione che gestisce automaticamente la nascita dello splashscreen per te (disponibile dalla versione 7.6.0):

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      directUpdate: 'always', // or 'atInstall'
      autoSplashscreen: true, // Automatically hide splashscreen
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false,
    },
  },
};

Quando autoSplashscreen è abilitato:

• Il plugin nasconde automaticamente lo splashscreen quando viene applicata un'aggiornamento
• Il plugin nasconde automaticamente lo splashscreen quando non è necessario un aggiornamento
• Non hai bisogno di ascoltare appReady eventi o chiamare SplashScreen.hide()

Gestione Manuale dello Splashscreen

Se preferisci avere il controllo manuale o hai bisogno di logica personalizzata, puoi disabilitare autoSplashscreen e gestirlo da solo:

import { CapacitorUpdater } from '@capgo/capacitor-updater';
import { SplashScreen } from '@capacitor/splash-screen';

CapacitorUpdater.addListener('appReady', () => {
  // Hide splash screen
  SplashScreen.hide();
});

CapacitorUpdater.notifyAppReady();

The appReady L'evento si attiva una volta che l'app ha completato l'inizializzazione e l'applicazione di eventuali aggiornamenti in sospeso. Questo è il punto in cui è sicuro mostrare l'interfaccia utente dell'app, poiché assicura che l'utente veda la versione più recente.

In aggiunta alla gestione dell'evento appReady consigliamo di impostare l'opzione di configurazione su keepUrlPathAfterReload quando si utilizza true Ciò preserva la cartella URL corrente quando l'app viene riavviata a causa di un aggiornamento, aiutando a mantenere la posizione dell'utente nell'app e riducendo la disorientamento. directUpdate__CAPGO_KEEP_0__

Se non gestisci l'evento e imposti appReady quando si utilizza keepUrlPathAfterReload il utente potrebbe vedere per breve tempo una versione obsoleta dell'app, essere riportato alla pagina iniziale o vedere un lampo mentre l'aggiornamento viene applicato. directUpdateL'utilizzo di

può essere utile per consegnare riparazioni critiche o patch di sicurezza, ma comporta alcuni compromessi: directUpdate Il utente potrebbe vedere un lampo o uno stato di caricamento per breve tempo mentre l'aggiornamento viene applicato se non gestisci correttamente lo schermo di benvenuto (in modo automatico con

• o con gestione manuale dell'evento). autoSplashscreen Se l'aggiornamento modifica lo stato dell'app o l'interfaccia utente, il utente potrebbe vedere un cambiamento disorientante in mezzo a una sessione. appReady La posizione del utente nell'app potrebbe essere persa se
• non è impostato, potenzialmente disorientandoli.
• If you don’t handle the __CAPGO_KEEP_0__ and set __CAPGO_KEEP_1__ when using __CAPGO_KEEP_2__, the user may briefly see a stale version of the app, be taken back to the initial route, or see a flicker as the update is applied. keepUrlPathAfterReload Using __CAPGO_KEEP_3__ can be useful for delivering critical bug fixes or security patches, but it comes with some tradeoffs:
• È necessario gestire con cura lo stato di salvataggio e di ripristino per garantire una transizione liscia.

Se abiliti directUpdate, consigliamo:

• Utilizzare autoSplashscreen: true per la configurazione più semplice, o gestire manualmente l' appReady evento se hai bisogno di logica personalizzata.
• Impostare keepUrlPathAfterReload su true per preservare la posizione dell'utente nell'applicazione.
• Salvare e ripristinare lo stato dell'applicazione quando necessario per evitare la perdita del progresso dell'utente.
• Testare attentamente il comportamento di aggiornamento dell'applicazione per garantire che non ci siano transizioni brusche, stato perso o cambiamenti di posizione disorientanti.

In molti casi, il comportamento di aggiornamento predefinito fornisce il miglior equilibrio tra la consegna di aggiornamenti rapidi e la minimizzazione della dislocazione. Ma per le app con esigenze specifiche, Capgo offre la flessibilità di personalizzare quando e come gli aggiornamenti vengono applicati.