Comportamento di 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 in mezzo a una sessione.

L'aggiornamento Capgo è progettato per bilanciare l'aggiornamento rapido e la minimizzazione della interruzione dell'esperienza utente.

Flusso di Aggiornamento Predefinito

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

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 ripetitore 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'applicazione.

3. Una volta completato il 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 avvisi 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?

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 avvisi 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 Vengono Applicati

In alcuni casi, potreste volere più controllo sulla precisione esatta quando un aggiornamento viene applicato. Ad esempio, potreste volere 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à ritardato fino a dopo il 1 giugno 2023 E l'applicazione è stata backgroundata per almeno 60 secondi.

Il condizionale disponibili sono:

• date: Attendere fino a dopo una data/ora specifica per applicare l'aggiornamento.
• background: Attendere un minimo di durata dopo che l'applicazione è stata backgroundata 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 miscelare e 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 consigliamo fortemente 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 al posto dell'intero bundle, il che è particolarmente importante quando gli aggiornamenti vengono applicati immediatamente mentre gli utenti stanno utilizzando la tua app.

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

• Aggiornamenti più veloci: Scarichi più piccoli significano che gli aggiornamenti si completano velocemente, riducendo il tempo in cui 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
• Un consumo di banda più basso: Vengono scaricati solo i file modificati, risparmiando dati sia per te che per i tuoi utenti

Quando autoUpdate è impostato "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. La versione legacy directUpdate del config è ancora rilevata. Utilizza --no-delta per forzare l'upload di un bundle completo.

Per 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'Alternativamente, puoi scegliere tra
• 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, ricade su "atBackground" comportamento
• 'always': Controlla ogni transizione in primo piano e applica immediatamente ogni volta che è 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 della versione nativa, della politica del canale e della 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 effettivamente controlla 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 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 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ò assicura di avere il controllo completo 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. La vostra app può quindi decidere quando chiamare CapacitorUpdater.set() o mostrare il proprio prompt di aggiornamento.

Gestione Automatica dello Schermo di Benvenuto

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

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

è abilitato: autoSplashscreen Il plugin nasconde automaticamente lo schermo di caricamento quando viene applicata un'aggiornamento

• Il plugin nasconde automaticamente lo schermo di caricamento quando non è necessario alcun aggiornamento
• Non è necessario ascoltare manualmente gli
• eventi o chiamare appReady Gestione manuale dello schermo di caricamento SplashScreen.hide()

Sezione intitolata “Gestione manuale dello schermo di caricamento”

Se preferisci 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();

Il appReady l'evento si attiva quando 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 istantaneo. 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 istantaneo, l'utente potrebbe vedere brevemente una versione obsoleta dell'app, essere riportato alla route iniziale o vedere un lampo mentre l'aggiornamento viene applicato.

__CAPGO_KEEP_0__ appReady __CAPGO_KEEP_1__ keepUrlPathAfterReload __CAPGO_KEEP_2__

Utilizzando un modalità di applicazione istantanea può essere utile per fornire correzioni di bug critici o patch di sicurezza, ma ciò 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 disorientandoli. keepUrlPathAfterReload Devi gestire con cura la salvaguardia 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 Devi gestire con cura la salvaguardia e il ripristino dello stato per garantire una transizione liscia. appReady Se abiliti l'applicazione istantanea, consigliamo:
• Configurazione keepUrlPathAfterReload a true contexto: Pagina/Area: Pagina prodotto live updates. Ruolo: Etichetta breve UI o elemento di navigazione. Chiave di messaggio `live_update_dynamic_label_to` (Live Update Dynamic Label To).
• 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.

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 di aggiornamenti rapidi e la minimizzazione della distruzione. Ma per le app con esigenze specifiche, __CAPGO_KEEP_0__ fornisce la flessibilità di 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 in tempo reale, connettilo con il Live Updates Capgo per il workflow del prodotto in Capgo Aggiornamenti in Tempo Reale, 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 Avvio rapido per i dettagli di implementazione in Avvio rapido.