Comportamento dell'aggiornamento

Quando rilasci 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 facendo aspettare che scarichino o riavviano l'app in mezzo a una sessione.

Capgo's comportamento di aggiornamento è progettato per bilanciare l'invio degli aggiornamenti in modo rapido e la minimizzazione della interruzione dell'esperienza degli utenti.

Flusso di Aggiornamento Predefinito

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

1. Quando 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 completato lo scarico, Capgo attende che l'utente chiuda l'app in background.

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

Questo flusso assicura che gli utenti siano sempre in esecuzione con 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 (impostazione predefinita 10 minuti).

Perché Questo Approccio?

Applicare gli 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 avvio dell'app è sempre fresca.

• Potete consegnare gli aggiornamenti frequentemente senza preoccuparvi di interrompere gli utenti attivi.

La principale svantaggio è che se un utente mette in background e ripristina velocemente il tuo app, potrebbero perdere lo stato non salvato poiché l'aggiornamento è stato applicato tra quelle azioni.

To 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 dell'aggiornamento per flussi sensibili (vedi di seguito).

Personalizzare Quando gli Aggiornamenti Sono Applicati

In alcuni casi, potresti voler avere più controllo sulla precisione esatta quando un aggiornamento viene applicato. Ad esempio, potresti voler assicurarti 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 ti consente di specificare condizioni che devono essere soddisfatte prima di installare un 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 tempo di attesa disponibile è:

• date: Attendere fino a una data/ora specifica per applicare l'aggiornamento.
• background: Attendere un minimo di durata dopo che l'app è 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: Wait until the next app kill event to apply the update.

Potete combinare e miscelare queste condizioni per controllare con precisione quando viene installato un aggiornamento.

Danger

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

Applicare Aggiornamenti Subito

For gli aggiornamenti critici o 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 il autoUpdate policy nel tuo Capacitor config.

Richiesto per l'applicazione istantanea: --delta, autoSplashscreen e SplashScreen

"atInstall", "onLaunch", e "always" applica l'aggiornamento mentre l'utente è in attesa. Utilizza Aggiornamenti Delta Solo i file modificati vengono scaricati. L'upload di un file zip completo rallenta l'esperienza utente.

Questi modi richiedono @capacitor/splash-screen e autoSplashscreen: true con SplashScreen.launchAutoHide: false. Senza il plugin di splash, l'utente può vedere un lampo o un'interfaccia utente obsoleta mentre l'aggiornamento si applica.

When autoUpdate è impostato su "atInstall", "onLaunch", o "always" nel tuo capacitor.configIn ambienti non interattivi, il CLI invia aggiornamenti Delta automaticamente, mentre in ambienti interattivi ti chiede di confermare prima di caricare. directUpdate per forzare l'upload di un bundle completo. --no-delta finestra del terminale

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

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

• false o 'off': Disable automatic update checks
• true o 'atBackground' Esegui automaticamente il controllo e il download ogni volta che l'app entra in primo piano, quindi applica l'aggiornamento la prossima volta che l'app si sposta in background
• '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, ricade su "atBackground" comportamento
• 'always'Controlla ogni volta che si passa a un'altra applicazione e applica immediatamente l'aggiornamento disponibile
• 'onlyDownload': Verifica e scarica automaticamente, emette updateAvailable, e non impostare mai il prossimo pacchetto o applicare un aggiornamento automaticamente

Testa una Build Nativa Senza Aggiornamenti in Tempo Reale

Vedi Testa le versioni native senza Live Update Per le misure di sicurezza native-version, politica del canale e configurazione 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;

Nota

Importante: i modi di applicazione istantanea applicano gli aggiornamenti solo quando il plugin effettivamente li controlla. 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 (10 minuti di default).

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

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

Attenzione

I modi di applicazione istantanea richiedono @capacitor/splash-screen e autoSplashscreen: true. Imposta launchAutoHide: false Nella configurazione di SplashScreen (come mostrato sopra) il splash screen rimane visibile fino a quando l'aggiornamento non è completato.

Scaricando Automaticamente Senza Applicare

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

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

In questo modo, il plugin emette updateAvailable dopo che è stato scaricato un bundle. La tua app può quindi decidere quando chiamare CapacitorUpdater.set() o mostrare il proprio prompt di aggiornamento.

Gestione automatica dello schermo di caricamento

I modi di applicazione istantanea (“"atInstall", "onLaunch", "always") richiedono autoSplashscreen e @capacitor/splash-screen ( disponibile dalla versione 7.6.0). Installa il plugin, poi mantieni visibile lo splash fino a quando Capgo lo nasconde:

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

When autoSplashscreen Quando

• The plugin nasconde automaticamente lo schermo di benvenuto quando viene applicata un'aggiornamento
• The plugin nasconde automaticamente lo schermo di benvenuto quando non è necessario un aggiornamento
• Non è necessario ascoltare manualmente per appReady eventi o chiamare SplashScreen.hide()

Lavoro extra dopo lo schermo si nasconde

Tieni autoSplashscreen: true. Se hai bisogno di logica extra dopo l'aggiornamento è pronto, ascolta anche appReady e non saltare il plugin dello schermo o autoSplashscreen per questo:

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

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

CapacitorUpdater.notifyAppReady();

The appReady l'evento si attiva una volta che l'app ha finito di inizializzare e di applicare eventuali aggiornamenti in sospeso.

Imposta keepUrlPathAfterReload al true quando si utilizza un modello di applicazione istantaneo. Ciò preserva la corrente URL di percorso quando l'app viene riavviata a causa di un aggiornamento.

L'uso di un modello di applicazione istantaneo può essere utile per fornire correzioni di bug critici o patch di sicurezza, ma comporta alcuni compromessi:

• Il utente potrebbe vedere un breve scintillio o stato di caricamento mentre l'aggiornamento viene applicato se @capacitor/splash-screen è mancante o autoSplashscreen non è abilitato.
• Se l'aggiornamento modifica lo stato dell'app o l'interfaccia utente, l'utente potrebbe vedere un cambiamento disorientante in mezzo a una sessione.
• Il percorso dell'utente nell'app potrebbe essere perso se keepUrlPathAfterReload non è impostato, potenzialmente disorientandolo.
• Devi gestire con cura la salvaguardia e il ripristino dello stato per garantire una transizione fluida.

Se abiliti l'applicazione istantanea, vi consigliamo:

• Caricare con npx @capgo/cli@latest bundle upload --delta in modo che il download non rallenti l'esperienza utente.
• Installare @capacitor/splash-screen e impostare autoSplashscreen: true con launchAutoHide: false.
• Impostare keepUrlPathAfterReload per true per preservare la posizione dell'utente nell'app.
• Salvare e ripristinare lo stato dell'app quando necessario per evitare la perdita del progresso dell'utente.
• Testare approfonditamente il comportamento dell'aggiornamento dell'app per assicurarsi 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.

Continua da Comportamento dell'aggiornamento

Se stai utilizzando Comportamento dell'aggiornamento per pianificare la consegna live update, connettilo con Capgo Aggiornamenti in tempo reale per il flusso di lavoro del prodotto in Capgo Live Updates, Overview per i dettagli di implementazione nella panoramica Features per i dettagli di implementazione nei Features, Tipi di Aggiornamento per i dettagli di implementazione in Tipi di Aggiornamento, e Getting Started per i dettagli di implementazione in Avvio.