Comportamento dell'aggiornamento

When you rilasciare un aggiornamento per il tuo Capgo app, probabilmente desideri che i tuoi utenti ricevano quell'aggiornamento il prima possibile. Ma non vuoi anche interrompere la loro esperienza obbligandoli a attendere il download o a riavviare l'app in mezzo a una sessione.

Capgo's comportamento di aggiornamento è progettato per trovare un equilibrio tra la consegna degli aggiornamenti velocemente e la minimizzazione della interruzione per i tuoi utenti.

Flusso di Aggiornamento Predefinito

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

1. When l'app si sposta in primo piano, il plugin Capgo controlla se è disponibile un nuovo aggiornamento. Mentre l'app rimane aperta, controlla nuovamente ogni volta che scade il timer ripetuto controllato da periodCheckDelay (10 minuti di default).

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

3. Una volta completata la download, Capgo attende che l'utente metta l'app in background.

4. Quando l'utente riporta l'app in primo piano, eseguirà la versione aggiornata.

Questo flusso garantisce che gli utenti stiano sempre eseguendo la versione più aggiornata dell'app, senza mai essere interrotti da richieste di aggiornamento o costretti a attendere i download.

Consiglio

Capgo controlla gli aggiornamenti ogni volta che l'app si sposta in primo piano e su un timer ripetuto mentre l'app rimane aperta. periodCheckDelay Controlla l'intervallo (predefinito 10 minuti).

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 richieste 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 avviare l'app è sempre fresca.

• Potete distribuire aggiornamenti frequenti senza preoccuparvi di interrompere gli utenti attivi.

Lo svantaggio principale è che se un utente mette in background e ripristina velocemente la vostra app, potrebbe perdere lo stato non salvato poiché l'aggiornamento è stato applicato tra quelle azioni.

Per mitigare questo, consigliamo:

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

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

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

Personalizzare Quando gli Aggiornamenti Sono Applicati

In alcuni casi, potreste volere più controllo sulla precisione esatta quando un aggiornamento viene applicato. Ad esempio, potreste voler assicurarvi che un 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 vi 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',
    },
  ],
});

Esempio: l'aggiornamento verrà installato solo dopo il 1 giugno 2023 E l'applicazione è stata messa in background per almeno 60 secondi.

Il condizionale disponibili sono:

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

È possibile combinare questi condizionali per controllare con precisione quando viene installato l'aggiornamento.

Danger

Nota che il kill condizionale attualmente attiva l'aggiornamento dopo l'evento di uccisione iniziale, non l'evento di background successivo come gli altri condizionali. Questa incoerenza verrà risolta in una versione futura.

Applicare Aggiornamenti Subito

Per gli aggiornamenti critici o per le app con uno stato molto semplice, potresti voler applicare un aggiornamento non appena è stato scaricato, senza attendere un evento di background o di chiusura. Capgo supporta questo tramite la autoUpdate policy nella tua Capacitor config.

Consigliato: Utilizza Aggiornamenti Delta (Manifesto) con Applicazione Istantanea

Quando si utilizza un modalità di applicazione istantanea, noi fortemente raccomandiamo di abilitare Aggiornamenti Delta (manifesto) per minimizzare i tempi di download e migliorare l'esperienza utente. Gli aggiornamenti delta (manifesto) scaricano solo i file modificati invece che l'intero pacchetto, il che è particolarmente importante quando gli aggiornamenti vengono applicati immediatamente mentre gli utenti stanno utilizzando la tua app.

Perché questo è importante per le modalità di applicazione istantanea:

• Aggiornamenti più veloci: Scarichi più piccoli significano che gli aggiornamenti si completano velocemente, riducendo il tempo che gli utenti vedono le schermate di caricamento
• Una migliore esperienza mobile: Gli utenti su reti cellulari o connessioni più lente non dovranno affrontare tempi di attesa lunghi
• Minore utilizzo di banda: Vengono scaricati solo i file modificati, risparmiando dati sia per te che per i tuoi utenti

Quando autoUpdate è impostato su "atInstall", "onLaunch", o "always" in tuo capacitor.config, il CLI lo rileva. In ambienti non interattivi invia gli aggiornamenti Delta (manifesto) automaticamente, e in ambienti interattivi ti chiede di confermare prima di caricare. Legacy directUpdate config è ancora rilevato. Utilizza --no-delta per forzare l'upload di un bundle completo.

To abilitare gli aggiornamenti Delta (manifesto), utilizza semplicemente il --delta flag quando si caricano i pacchetti:

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

Scopri di più nella documentazione degli aggiornamenti Delta (manifesto).

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

• false o 'off'Alternativa: Appflow, Capawesome o consultare un esperto
• true : Disabilita le verifiche automatiche degli aggiornamenti 'atBackground' o
• 'atInstall': Applica immediatamente solo dopo un'installazione fresca o un aggiornamento dell'applicazione nativa; altrimenti utilizza "atBackground" comportamento
• 'onLaunch': Applica immediatamente solo quando l'app viene riportata in primo piano da uno stato ucciso (avvio freddo). Dopo la prima verifica, ricadere su "atBackground" comportamento
• 'always': Controlla ogni transizione in primo piano e applica immediatamente quando è disponibile un aggiornamento
• 'onlyDownload': Controlla e scarica automaticamente, emiti updateAvailable, e non impostare mai il prossimo pacchetto o applicare un aggiornamento automaticamente

Testa una costruzione nativa senza aggiornamenti in tempo reale

Vedi Testare le costruzioni native senza aggiornamenti in tempo reale per le salvaguardie di configurazione di versione nativa, politica di canale 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 when using instant apply with autoSplashscreen
    },
  },
};

export default config;

Nota

Importante: i modi di applicazione istantanea applicano gli aggiornamenti solo quando il plugin controlla effettivamente per loro. Di default, le verifiche vengono eseguite quando l'app si sposta in primo piano e su un timer ripetuto mentre l'app rimane aperta. periodCheckDelay controlla quell'intervallo (di default 10 minuti).

Con autoUpdate: 'always', Capgo controlla ogni volta che l'app si sposta in primo piano e applica immediatamente l'aggiornamento non appena la scarica si completa durante quel controllo, anche se l'utente sta utilizzando attivamente l'app. Le verifiche periodiche controllate da periodCheckDelay possono attivare lo stesso comportamento di applicazione immediata mentre l'app rimane aperta.

Nota che poiché autoUpdate è una configurazione nativa, i modi di applicazione istantanea richiedono alcune ulteriori gestione nel tuo JavaScript code.

Attenzione

Quando si utilizza il modalità di applicazione istantanea con autoSplashscreen, è necessario impostare launchAutoHide: false in la configurazione SplashScreen (come mostrato sopra) per impedire che lo schermo di benvenuto si nasconda automaticamente. Ciò consente di avere il pieno controllo sul momento in cui lo schermo di benvenuto viene nascosto dopo la conclusione del processo di aggiornamento.

Scaricamento Automatico Senza Applicazione

Se desiderate che Capgo controlli e scarichi gli aggiornamenti automaticamente, ma non li applichi mai automaticamente, utilizzate autoUpdate: 'onlyDownload':

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

In questo modo, il plugin emette updateAvailable dopo il download di un bundle. L'applicazione può quindi decidere quando chiamare CapacitorUpdater.set() o mostrare il proprio prompt di aggiornamento.

Gestione dello Schermo di Benvenuto Automatica

Per rendere più facili da utilizzare i modi di applicazione istantanea, Capgo fornisce un' autoSplashscreen opzione che gestisce automaticamente la nascita dello schermo di caricamento per te (disponibile dalla versione 7.6.0):

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 schermo di caricamento quando viene applicata un'aggiornamento
• Il plugin nasconde automaticamente lo schermo di caricamento quando non è necessario un aggiornamento
• Non è necessario ascoltare manualmente gli appReady eventi o chiamare SplashScreen.hide()

Gestione manuale dello schermo di caricamento

Se preferisci il controllo manuale o hai bisogno di logica personalizzata, puoi disabilitare autoSplashscreen e gestirlo tu stesso:

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

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

CapacitorUpdater.notifyAppReady();

Il appReady l'evento si attiva una volta che l'app ha finito di inizializzare e di applicare 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.

Inoltre, oltre a gestire l'evento, raccomandiamo di impostare l'opzione di configurazione su appReady quando si utilizza un modello di applicazione istantanea. 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. keepUrlPathAfterReload Se non gestisci l'evento e imposti true quando si utilizza un modello di applicazione istantanea, l'utente potrebbe vedere brevemente una versione obsoleta dell'app, essere riportato alla route iniziale o vedere un lampo mentre l'aggiornamento viene applicato.

Copy to clipboard appReady The keepUrlPathAfterReload event fires once the app has finished initializing and applying any pending updates. This is the point at which it’s safe to show your app’s UI, as it ensures the user will see the latest version.

Utilizzando un modalità di applicazione istantanea può essere utile per fornire correzioni di bug critici o patch di sicurezza, ma comporta alcuni compromessi:

• Lo utente potrebbe vedere un breve scintillio o stato di caricamento mentre l'aggiornamento viene applicato se non gestisci correttamente lo schermo di benvenuto (in modo automatico o manuale) autoSplashscreen con l'eventuale gestione dell'evento appReady Se l'aggiornamento modifica lo stato dell'applicazione o l'interfaccia utente, lo utente potrebbe vedere un cambiamento disorientante in mezzo a una sessione.
• La posizione dell'utente nell'applicazione potrebbe essere persa se non è impostato il
• potenzialmente disorientandolo. keepUrlPathAfterReload Devi gestire con cura la salvataggio e il ripristino dello stato per garantire una transizione liscia.
• Se abiliti l'applicazione istantanea, consigliamo:

Utilizzare

• per la configurazione più semplice, o gestire manualmente l'evento se hai bisogno di logica personalizzata. autoSplashscreen: true Utilizzare __CAPGO_KEEP_0__ per la configurazione più semplice, o gestire manualmente l'__CAPGO_KEEP_1__ se hai bisogno di logica personalizzata. appReady Utilizzare __CAPGO_KEEP_0__ per la configurazione più semplice, o gestire manualmente l'__CAPGO_KEEP_1__ se hai bisogno di logica personalizzata.
• Configurazione keepUrlPathAfterReload a true contexto: Pagina/Area: Pagina prodotti live updates. Ruolo: Etichetta breve UI o elemento di navigazione. Chiave di messaggio `live_update_dynamic_label_to` (Live Update Dynamic Label To).
• per mantenere la posizione dell'utente nell'applicazione.
• Salvare e ripristinare lo stato dell'applicazione quando necessario per evitare la perdita del progresso dell'utente.

In most cases, the default update behavior provides the best balance of delivering updates quickly and minimizing disruption. But for apps with specific needs, Capgo provides the flexibility to customize when and how updates are applied.

In molti casi, il comportamento di aggiornamento predefinito fornisce il miglior equilibrio tra la consegna degli aggiornamenti in modo rapido e la minimizzazione della distruzione. Ma per le app con esigenze specifiche, __CAPGO_KEEP_0__ fornisce la flessibilità per personalizzare quando e come gli aggiornamenti vengono applicati.

Sottosezione intitolata “Continua da qui: Comportamento dell'aggiornamento” Se stai utilizzando Comportamento dell'aggiornamento per pianificare la consegna degli aggiornamenti live, connettilo con il live update Capgo per il workflow del prodotto in Capgo Live Updates Panoramica per i dettagli di implementazione in Panoramica Caratteristiche per i dettagli di implementazione in Caratteristiche Tipi di Aggiornamento per i dettagli di implementazione in Tipi di Aggiornamento, e Iniziare per i dettagli di implementazione in Iniziare