Comportamento degli aggiornamenti

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

Quando pubblichi un aggiornamento per la tua app Capgo, probabilmente vuoi che gli utenti lo ricevano il prima possibile. Ma non vuoi nemmeno interrompere la loro esperienza costringendoli ad aspettare un download o a riavviare l'app in mezzo a una sessione.

Il comportamento di aggiornamento di Capgo è progettato per bilanciare la consegna rapida degli aggiornamenti e la minimizzazione delle interruzioni per i tuoi utenti.

Flusso di update predefinito

Di default, ecco come Capgo gestisce gli aggiornamenti dell'app:

Quando l'app passa in primo piano, il plugin Capgo verifica se è disponibile un nuovo aggiornamento. Mentre l'app resta aperta, esegue anche un controllo periodico su un timer ripetuto controllato da periodCheckDelay (default 10 minuti).
Se viene trovato un aggiornamento, viene scaricato in background mentre l'utente continua a usare la versione corrente dell'app.
Una volta completato il download, Capgo attende che l'utente metta l'app in background.
Quando l'utente riporta l'app in primo piano, eseguirà la versione aggiornata.

Questo flusso garantisce che gli utenti utilizzino sempre l'ultima versione della tua app, senza mai essere interrotti da prompt di aggiornamento o costretti ad aspettare i download.

Perché questo approccio?

Applicare gli aggiornamenti in background o alla chiusura forzata offre alcuni vantaggi chiave per l'esperienza utente:

Gli utenti non vengono interrotti da prompt di aggiornamento o costretti ad attendere i download durante una sessione.
Gli aggiornamenti vengono applicati in modo trasparente tra una sessione e l'altra, così l'app si avvia sempre aggiornata.
Puoi rilasciare aggiornamenti con frequenza senza preoccuparti di disturbare gli utenti attivi.

Lo svantaggio principale è che se un utente manda l'app in background e la riprende subito, potrebbe perdere lo stato non salvato, dato che l'aggiornamento è stato applicato tra le due azioni.

Per mitigare questo problema, consigliamo di:

Salvare lo stato spesso e ripristinarlo in modo corretto quando l'app torna attiva.
Evitare aggiornamenti troppo frequenti che modificano ampie parti dello stato dell'app.
Valuta di personalizzare il comportamento degli aggiornamenti per i flussi sensibili (vedi sotto).

Personalizzare quando applicare gli update

In alcuni casi, potresti voler avere un controllo più preciso su quando viene applicato un aggiornamento. Ad esempio, potresti voler assicurarti che un utente completi un flusso in corso prima dell'aggiornamento, o coordinare un aggiornamento dell'app con una modifica lato server.

Capgo fornisce una setDelay funzione che ti consente di specificare le condizioni che devono essere soddisfatte prima che un aggiornamento venga installato:

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 finché l'app non sarà stata in background per almeno 60 secondi.

Le condizioni di ritardo disponibili sono:

date: Aspetta fino a dopo una data/ora specifica per applicare l'aggiornamento.
background: Aspetta una durata minima dopo che l'app è in background per applicare l'aggiornamento.
nativeVersion: Aspetta che venga installato un binario nativo con una versione minima prima di applicare l'aggiornamento.
kill: In attesa del prossimo evento di chiusura dell'app per applicare l'aggiornamento.

Puoi combinare queste condizioni per controllare con precisione quando viene installato un aggiornamento.

Applicare gli update immediatamente

Per aggiornamenti critici o app con uno stato molto semplice, potresti voler applicare un aggiornamento non appena viene scaricato, senza attendere un evento in background o di chiusura. Capgo supporta questa funzionalità tramite la autoUpdate policy nella configurazione Capacitor.

"atInstall", "onLaunch", e "always" applica l'update mentre l'utente è in attesa. Usa Aggiornamenti delta così vengono scaricati solo i file modificati. Un upload completo in zip rallenta l'esperienza utente.

Queste modalità richiedono anche @capacitor/splash-screen e autoSplashscreen: true con SplashScreen.launchAutoHide: false. Senza il plugin splash, l'utente potrebbe vedere un flicker o un'UI obsoleta durante l'applicazione dell'update.

Quando autoUpdate è impostato su "atInstall", "onLaunch", o "always" nel tuo capacitor.config, il CLI lo rileva. Negli ambienti non interattivi invia automaticamente gli aggiornamenti Delta, mentre in quelli interattivi ti chiede conferma prima dell'upload. La configurazione directUpdate legacy viene ancora rilevata. Usa --no-delta per forzare l'upload di un bundle completo.

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

autoUpdate è impostato nel tuo capacitor.config.ts file, non in JavaScript code. Supporta questi valori:

false oppure 'off': Disable automatic update checks
true oppure 'atBackground' (predefinito): Controlla e scarica automaticamente a ogni verifica in foreground, quindi applica l'aggiornamento la prossima volta che l'app passa in background
'atInstall': Applica immediatamente solo dopo un'installazione fresca o un aggiornamento dall'app store nativo; altrimenti usa "atBackground" comportamento
'onLaunch': Applica immediatamente solo quando l'app viene riportata in primo piano da uno stato terminato (cold start). Dopo il primo controllo, passa a "atBackground" comportamento
'always': Controlla a ogni transizione in primo piano e applica immediatamente quando è disponibile un aggiornamento
'onlyDownload': Controlla e scarica automaticamente, emetti updateAvailable, e non impostare mai il bundle successivo né applicare un aggiornamento automaticamente

Testare un Native Build senza Live Updates

Vedi Testa le Native Build senza Live Updates per i salvaguardie di configurazione relative a native-version, channel-policy e CI.

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

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'always', // or 'atInstall' for updates only on app install/update
      autoSplashscreen: true,
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false, // Required for instant apply with autoSplashscreen
    },
  },
};

export default config;

Con autoUpdate: 'always', Capgo esegue controlli a ogni transizione in foreground e applica immediatamente l'aggiornamento non appena il download termina durante il controllo, anche se l'utente sta usando l'app. I controlli periodici gestiti da periodCheckDelay possono attivare lo stesso comportamento di applicazione immediata mentre l'app resta aperta.

Nota che, poiché autoUpdate si tratta di una configurazione nativa, le modalità instant apply richiedono una gestione aggiuntiva nel tuo code JavaScript.

Download automatico senza applicare

Se vuoi che Capgo verifichi e scarichi gli aggiornamenti automaticamente, ma non li applichi mai in automatico, usa autoUpdate: 'onlyDownload':

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'onlyDownload',
    },
  },
};

In questa modalità, il plugin emette updateAvailable dopo il download di un bundle. La tua app può quindi decidere quando chiamare CapacitorUpdater.set() o mostrare il proprio prompt di aggiornamento.

Gestione automatica dello splashscreen

Modalità di applicazione istantanea ("atInstall", "onLaunch", "always") richiedono autoSplashscreen e @capacitor/splash-screen (disponibile dalla versione 7.6.0). Installa il plugin, poi mantieni lo splash visibile finché Capgo non lo nasconde:

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

Quando autoSplashscreen è abilitato:

Il plugin nasconde automaticamente lo splash screen quando viene applicato un update
Il plugin nasconde automaticamente lo splash screen quando non è necessario alcun update
Non è necessario ascoltare manualmente appReady gli eventi o chiamare SplashScreen.hide()

Operazioni extra dopo la chiusura dello splash

Mantieni autoSplashscreen: true. Se ti serve della logica extra dopo che l'update è pronto, ascolta appReady anche. Non saltare il plugin splash o autoSplashscreen per questo:

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

CapacitorUpdater.addListener('appReady', () => {
  // Update is applied. autoSplashscreen already hid the splash.
});

CapacitorUpdater.notifyAppReady();

Il appReady l'evento viene attivato quando l'app ha terminato l'inizializzazione e l'applicazione di eventuali update pendenti.

Imposta keepUrlPathAfterReload a true quando usi una modalità instant apply. Questo mantiene il percorso URL corrente quando l'app viene ricaricata per un update.

L'uso della modalità di applicazione istantanea può essere utile per distribuire correzioni di bug critiche o patch di sicurezza, ma comporta alcuni compromessi:

L'utente potrebbe notare un breve lampeggio o uno stato di caricamento durante l'applicazione dell'aggiornamento se @capacitor/splash-screen è assente o autoSplashscreen non è abilitato.
Se l'update modifica lo stato dell'app o l'UI, l'utente potrebbe notare un cambiamento fastidioso a metà sessione.
La posizione dell'utente nell'app potrebbe andare persa se keepUrlPathAfterReload non è impostato, rischiando di disorientarlo.
Dovrai gestire con attenzione il salvataggio e il ripristino dello stato per garantire una transizione fluida.

Se abiliti l'applicazione istantanea, ti consigliamo di:

Caricare con npx @capgo/cli@latest bundle upload --delta in modo che il download non rallenti l'esperienza utente.
Installare @capacitor/splash-screen e configurazione autoSplashscreen: true con launchAutoHide: false.
Impostazione keepUrlPathAfterReload a true per preservare la posizione dell'utente nell'app.
Salvare e ripristinare lo stato dell'app quando necessario per evitare di perdere i progressi dell'utente.
Testa accuratamente il comportamento degli aggiornamenti della tua app per evitare transizioni brusche, perdita di stato o cambi di posizione disorientanti.

Nella maggior parte dei casi, il comportamento di aggiornamento predefinito offre il miglior equilibrio tra la consegna rapida degli aggiornamenti e la minimizzazione delle interruzioni. Ma per le app con esigenze specifiche, Capgo offre la flessibilità di personalizzare quando e come vengono applicati gli aggiornamenti.

Continua con il comportamento degli update

Se stai usando Comportamento degli aggiornamenti per pianificare la distribuzione di live update, collegalo a Live Updates di Capgo per il workflow del prodotto in Capgo Live Updates, Panoramica per i dettagli di implementazione nell'Overview, Funzionalità per i dettagli implementativi in Features, Tipi di aggiornamento per i dettagli sull'implementazione in Update Types, e Per iniziare per i dettagli sull'implementazione in Getting Started.