Update-Verhalten

Wenn du ein Update für deine Capgo App veröffentlichst, möchten deine Nutzer dieses wahrscheinlich so schnell wie möglich erhalten. Gleichzeitig willst du ihr Erlebnis nicht stören, indem du sie zum Download zwingst oder die App mitten in einer Session neu starten lässt.

Das Update-Verhalten von Capgo ist darauf ausgelegt, eine Balance zwischen schnellen Updates und minimalen Unterbrechungen für deine Nutzer zu finden.

Standard-Update-Flow

Standardmäßig verarbeitet Capgo App-Updates wie folgt:

1. Sobald die App in den Vordergrund tritt, prüft das Capgo Plugin, ob ein neues Update verfügbar ist. Solange die App geöffnet bleibt, erfolgt eine weitere Prüfung über einen Timer, der von gesteuert wird, periodCheckDelay (standardmäßig 10 Minuten).

2. Wird ein Update gefunden, wird es im Hintergrund heruntergeladen, während der Nutzer die aktuelle Version der App weiter verwendet.

3. Sobald der Download abgeschlossen ist, wartet Capgo, bis der Nutzer die App in den Hintergrund schiebt.

4. Wenn der Nutzer die App das nächste Mal in den Vordergrund holt, wird die aktualisierte Version ausgeführt.

Dieser Flow stellt sicher, dass Nutzer immer die neueste Version deiner App verwenden, ohne durch Update-Prompts unterbrochen zu werden oder auf Downloads warten zu müssen.

Tipp

Capgo prüft auf Updates, sobald die App in den Vordergrund tritt, sowie in regelmäßigen Abständen, solange die App geöffnet ist. periodCheckDelay steuert dieses Intervall (Standard: 10 Minuten).

Warum dieser Ansatz?

Updates im Hintergrund oder bei einem Kill-Event anzuwenden, bietet entscheidende Vorteile für die User Experience:

• Nutzer werden nicht durch Update-Prompts unterbrochen oder gezwungen, mitten in einer Session auf Downloads zu warten.

• Updates werden nahtlos zwischen den Sitzungen angewendet, sodass sich das Starten der App immer wie neu anfühlt.

• Du kannst häufig Updates ausliefern, ohne aktive Nutzer zu stören.

Der Hauptnachteil ist: Wenn ein Nutzer die App kurz in den Hintergrund schiebt und sofort wieder öffnet, kann ungespeicherter State verloren gehen, falls das Update genau dazwischen angewendet wurde.

Um dies zu minimieren, empfehlen wir:

• Den State häufig zu speichern und ihn beim App-Resume sauber wiederherzustellen.

• Sehr häufige Updates zu vermeiden, die große Teile des App-States verändern.

• Für sensible Abläufe empfiehlt sich eine Anpassung des Update-Verhaltens (siehe unten).

Anpassung des Update-Zeitpunkts

In manchen Fällen benötigen Sie mehr Kontrolle darüber, wann genau ein Update angewendet wird. Sie möchten beispielsweise sicherstellen, dass ein Nutzer einen laufenden Prozess abschließt, bevor das Update erfolgt, oder ein App-Update mit einer serverseitigen Änderung koordinieren.

Capgo bietet eine setDelay Funktion an, mit der Sie Bedingungen festlegen können, die vor der Installation eines Updates erfüllt sein müssen:

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

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

Dieses Beispiel verzögert die Installation eines Updates bis nach dem 1. Juni 2023 UND nachdem die App mindestens 60 Sekunden im Hintergrund war.

Folgende Delay-Bedingungen stehen zur Verfügung:

• date: Warten, bis ein bestimmtes Datum/Uhrzeit erreicht ist, um das Update anzuwenden.
• background: Warten einer Mindestdauer, nachdem die App in den Hintergrund gegangen ist, um das Update anzuwenden.
• nativeVersion: Warten, bis ein Native Build mit einer Mindestversion installiert ist, bevor das Update angewendet wird.
• kill: Warte auf das nächste App-Kill-Event, um das Update anzuwenden.

Du kannst diese Bedingungen kombinieren, um genau zu steuern, wann ein Update installiert wird.

Achtung

Beachte, dass die kill Bedingung das Update aktuell nach dem ersten Kill-Event auslöst und nicht nach dem nächsten Background-Event wie die anderen Bedingungen. Diese Inkonsistenz wird in einem zukünftigen Release behoben.

Updates sofort anwenden

Bei kritischen Updates oder Apps mit sehr einfachem State möchtest du ein Update eventuell sofort nach dem Download anwenden, ohne auf ein Background- oder Kill-Event zu warten. Capgo unterstützt dies über die autoUpdate Policy in deiner Capacitor Config.

Für sofortiges Anwenden erforderlich: --delta, autoSplashscreen und SplashScreen

"atInstall", "onLaunch", und "always" während der User wartet, das Update anzuwenden. Nutze Delta-Updates so only changed files download. A full zip upload slows the user experience.

Diese Modi erfordern zudem @capacitor/splash-screen und autoSplashscreen: true mit SplashScreen.launchAutoHide: false. Ohne das Splash-Plugin sieht der User eventuell ein Flackern oder eine veraltete UI, während das Update angewendet wird.

Wenn autoUpdate auf gesetzt ist "atInstall", "onLaunch", oder "always" in deiner capacitor.config, erkennt dies CLI. In nicht-interaktiven Umgebungen werden Delta-Updates automatisch gesendet; in interaktiven Umgebungen wirst du vor dem Upload um Bestätigung gebeten. Legacy- directUpdate Konfiguration wird weiterhin erkannt. Nutze --no-delta , um einen vollständigen Bundle-Upload zu erzwingen.

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

autoUpdate ist in deiner capacitor.config.ts Datei, nicht in der JavaScript code. Es unterstützt diese Werte:

• false oder 'off': Automatische Update-Checks deaktivieren
• true oder 'atBackground' (Standard): Bei jedem Foreground-Check automatisch prüfen und herunterladen, dann das Update beim nächsten Wechsel in den Background anwenden
• 'atInstall': Nur nach einer Neuinstallation oder einem nativen App-Store-Update sofort anwenden; ansonsten verwenden "atBackground" Verhalten
• 'onLaunch': Nur sofort anwenden, wenn die App aus einem beendeten Zustand in den Vordergrund geholt wird (Cold Start). Nach dieser ersten Prüfung Fallback auf "atBackground" Verhalten
• 'always': Bei jedem Wechsel in den Vordergrund prüfen und sofort anwenden, sobald ein Update verfügbar ist
• 'onlyDownload': Automatisch prüfen und herunterladen, emittieren updateAvailable, und niemals das nächste Bundle setzen oder ein Update automatisch anwenden

Ein Native Build ohne Live Updates testen

Siehe Native Builds ohne Live Updates testen für die Absicherungen bei native-version, channel-policy und CI-Konfiguration.

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;

Hinweis

Wichtig: Die Instant-Apply-Modi wenden Updates nur an, wenn das Plugin tatsächlich nach ihnen sucht. Standardmäßig erfolgen die Checks, wenn die App in den Vordergrund wechselt, sowie in regelmäßigen Abständen, solange die App geöffnet ist. periodCheckDelay steuert dieses Intervall (Standard: 10 Minuten).

Mit autoUpdate: 'always', Capgo prüft bei jedem Wechsel in den Vordergrund und wendet ein Update sofort nach Abschluss des Downloads an – selbst wenn der User die App gerade aktiv nutzt. Periodische Checks, gesteuert durch periodCheckDelay können das gleiche sofortige Anwenden auslösen, während die App geöffnet bleibt.

Beachte, dass da autoUpdate eine native Konfiguration ist, benötigen Instant-Apply-Modi zusätzliche Logik in deinem JavaScript code.

Achtung

Instant-Apply-Modi erfordern @capacitor/splash-screen und autoSplashscreen: true. Setze launchAutoHide: false in der SplashScreen-Konfiguration (wie oben gezeigt), damit der Splashscreen sichtbar bleibt, bis das Update abgeschlossen ist.

Automatisch herunterladen ohne Anwenden

Wenn Capgo Updates automatisch prüfen und herunterladen, diese aber niemals automatisch anwenden soll, nutze autoUpdate: 'onlyDownload':

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

In diesem Modus gibt das Plugin updateAvailable aus, nachdem ein Bundle heruntergeladen wurde. Deine App kann dann entscheiden, wann sie CapacitorUpdater.set() oder einen eigenen Update-Prompt anzeigt.

Automatisches Splashscreen-Handling

Instant-Apply-Modi ("atInstall", "onLaunch", "always") erforderlich autoSplashscreen und @capacitor/splash-screen (verfügbar ab Version 7.6.0). Installiere das Plugin und halte den Splashscreen sichtbar, bis Capgo ihn ausblendet:

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

Wenn autoSplashscreen aktiviert ist:

• Das Plugin blendet den Splashscreen automatisch aus, sobald ein Update angewendet wurde
• Das Plugin blendet den Splashscreen automatisch aus, wenn kein Update benötigt wird
• Du musst nicht manuell auf appReady Events warten oder SplashScreen.hide()

Extra work after the splash hides

Behalte autoSplashscreen: true. Wenn Sie nach dem Update zusätzliche Logik benötigen, lauschen Sie auf appReady ebenfalls. Überspringen Sie das Splash-Plugin nicht oder autoSplashscreen hierfür:

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

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

CapacitorUpdater.notifyAppReady();

Die appReady das Event wird gefeuert, sobald die App die Initialisierung und das Anwenden ausstehender Updates abgeschlossen hat.

Setze keepUrlPathAfterReload zu true bei Verwendung des Instant-Apply-Modus. Dies bewahrt den aktuellen URL-Pfad, wenn die App aufgrund eines Updates neu geladen wird.

Der Instant-Apply-Modus ist nützlich für kritische Bugfixes oder Security-Patches, bringt aber gewisse Kompromisse mit sich:

• Der Nutzer sieht eventuell ein kurzes Flackern oder einen Ladezustand, während das Update angewendet wird, wenn @capacitor/splash-screen fehlt oder autoSplashscreen nicht aktiviert ist.
• Falls das Update den App-State oder die UI verändert, kann es mitten in einer Session zu störenden Änderungen kommen.
• Der Standort des Nutzers in der App kann verloren gehen, wenn keepUrlPathAfterReload nicht gesetzt ist, was zu Desorientierung führen kann.
• Du musst das Speichern und Wiederherstellen des States sorgfältig handhaben, um einen reibungslosen Übergang zu gewährleisten.

Falls du Instant Apply aktivierst, empfehlen wir:

• Das Uploaden mit npx @capgo/cli@latest bundle upload --delta damit der Download die User Experience nicht verlangsamt.
• Installing @capacitor/splash-screen und Einstellen autoSplashscreen: true mit launchAutoHide: false.
• Einstellen keepUrlPathAfterReload zu true um den Standort des Nutzers in der App zu erhalten.
• Speichern und Wiederherstellen des App-States nach Bedarf, um den Fortschritt des Nutzers nicht zu verlieren.
• Testen Sie das Update-Verhalten Ihrer App gründlich, um ruckartige Übergänge, Zustandsverluste oder desorientierende Standortänderungen zu vermeiden.

In den meisten Fällen bietet das Standard-Update-Verhalten die beste Balance zwischen schnellen Updates und minimalen Unterbrechungen. Aber für Apps mit speziellen Anforderungen bietet Capgo die Flexibilität, anzupassen, wann und wie Updates angewendet werden.

Weiter mit Update-Verhalten

Wenn Sie ... verwenden Update-Verhalten Um die Auslieferung von live update zu planen, verbinde sie mit Capgo Live Updates für den Produkt-Workflow in Capgo Live Updates, Übersicht für die Implementierungsdetails in der Übersicht, Funktionen für die Implementierungsdetails im Abschnitt Features, Update-Typen für die Details zu den Update-Typen und Erste Schritte für die Details unter Getting Started.