Getting Started

Installieren

npm install @capgo/capacitor-webview-crash
npx cap sync

Importieren

import { WebViewCrash } from '@capgo/capacitor-webview-crash';

Empfohlener Wiederherstellungsfluss

Fügen Sie Listener so früh wie möglich in der App-Startzeit ein, damit das wiederhergestellte Runtime reagieren kann, bevor Benutzer weiterhin navigieren:

import { WebViewCrash } from '@capgo/capacitor-webview-crash';

await WebViewCrash.addListener('webViewRestoredAfterCrash', async (info) => {
  console.log('Recovered after a WebView crash', info);

  // Rehydrate critical state, reopen the correct screen, or prompt the user to retry.
  await WebViewCrash.clearPendingCrashInfo();
});

await WebViewCrash.addListener('webViewRestoredAfterRestart', async (info) => {
  console.log('Recovered after a native WebView restart', info);
  await WebViewCrash.clearPendingCrashInfo();
});

const pending = await WebViewCrash.getPendingCrashInfo();
// Note: the listener callback may have already cleared the pending marker.
if (pending.value) {
  console.log('Pending crash or restart marker', pending.value);
}

Natives Auto-Neustarten

Neustartoptionen in capacitor.config.ts damit die Entscheidung im native code bleibt, selbst wenn der JavaScript-Interpreter abgestürzt ist oder nicht geladen wurde:

import type { CapacitorConfig } from '@capacitor/cli';
import type { WebViewCrashPluginConfig } from '@capgo/capacitor-webview-crash';

const webViewCrash: WebViewCrashPluginConfig = {
  // Enabled by default. Keep this on for long-running apps.
  restartOnCrash: true,

  // Use a 5-field cron schedule in the device local timezone.
  // Do not combine restartCron with an active restartIntervalMs.
  restartCron: '0 3 * * *',

  // Optional delay before restarting after a crash.
  restartAfterCrashDelayMs: 0,
};

const config: CapacitorConfig = {
  plugins: {
    WebViewCrash: webViewCrash,
  },
};

export default config;

Verwenden restartIntervalMs für Apps, die immer eingeschaltet sind, bei denen die Benutzer den gleichen WebView über Tage hinweg offen halten: Kiosk-Screens, Steuerungszentralen, Lager-Scannern, POS-Terminals, Flotten-Tablets und digitale Anzeigen. Verwenden restartCron für Walluhr-Neustarts wie 0 3 * * * für einen täglichen Neustart um 03:00 Uhr in der Gerätegaufahrtszeitzone. Geplante Neustarts schreiben einen wartenden Marker mit reason: 'periodicRestart', dann wird Android die Hostaktivität neu erstellt und iOS die Capacitor-Brückeansicht neu erstellt, sodass ein neuer WKWebView aus dem native code erstellt wird.

Wählen Sie einen Zeitraum oder eine Cron-Auftragsplanung, die Ihr Produkt tolerieren kann. restartCron __CAPGO_KEEP_0__ *unterstützt Listen, Ränge und Schritte. Konfigurieren Sie nicht beide Schedules gleichzeitig: Die native Initialisierung wirft einen fatalen Konfigurationsfehler, wenn "is set" und "is greater than" gleichzeitig gesetzt sind. Ein Neustart erstellt ein frisches JavaScript- Runtime, daher müssen Sie vor der Verwendung aggressiver Schedules die angesammelten Ereignisse, ungelesene Formulare und den aktuellen Navigationszustand persistieren. restartCron Manueller native Neustart restartIntervalMs Abschnitt mit dem Titel “Manueller native Neustart” 0Aufrufen Sie

wenn der aktuelle JavaScript-Runtime entscheidet, dass der native WebView vorzeitig ersetzt werden sollte, zum Beispiel nach einem memory-intensiven Workflow oder bevor eine lange unbesetzte Sitzung beginnt:

Die Methode schreibt einen vorläufigen Marker mit restartWebView() when the current JavaScript runtime decides the native WebView should be replaced proactively, for example after a memory-heavy workflow or before entering a long unattended session:

await WebViewCrash.restartWebView();

The method writes a pending marker with reason: 'manualRestart' löst die aktuelle Anrufung auf und fragt den native code auf, einen frischen WebView zu erstellen. Android reaktualisiert die Hostaktivität. iOS reaktualisiert die Capacitor Bridgeansicht, sodass eine neue WKWebView wird anstatt die aktuelle Seite neu zu laden.

API Übersicht

getPendingCrashInfo

Gibt die gespeicherte native Crash- oder Neustartmarke zurück, oder null wenn nichts im Voraus steht.

const pending = await WebViewCrash.getPendingCrashInfo();
if (pending.value) {
  console.log(pending.value.platform, pending.value.reason);
}

clearPendingCrashInfo

Löscht die gespeicherte Marke, nachdem Ihre Wiederherstellungsverarbeitung abgeschlossen ist.

await WebViewCrash.clearPendingCrashInfo();

simulateCrashRecovery

Erstellt einen fiktiven Crashmarker, damit sich QA und lokale Debugging auf die Wiederherstellungsroute ohne Absturz eines echten WebView ausüben können.

const simulated = await WebViewCrash.simulateCrashRecovery();
console.log(simulated.value);

restartWebView

Speichert einen manuellen Neustartmarker und fragt den native code nach, einen frischen WebView zu erstellen.

await WebViewCrash.restartWebView();

Plattformhinweise

• Android speichert Crashmetadaten von onRenderProcessGoneeinschließlich didCrash und rendererPriorityAtExit wenn die Plattform sie bereitstellt.
• iOS speichert Crashmetadaten von webViewWebContentProcessDidTerminate und fügt dem aktuellen Anwendungsstatus hinzu, wenn verfügbar.
• Manuelle und geplante Neustarts erstellen eine frische WebView. Android wiederholt die Hostaktivität; iOS rekonstruiert die Capacitor Bridgeansicht.
• Geplante Neustarts verwenden reason: 'periodicRestart'; manuelle Neustarts verwenden reason: 'manualRestart'.
• Web erkennt keine echten Renderercrashes. Die Web-Implementierung simuliert nur das Verhalten mit lokalen Speicher.

Typenverweis

PendingCrashInfoResult

export interface PendingCrashInfoResult {
  /**
   * Stored crash or restart metadata, or `null` when no marker is pending.
   */
  value: WebViewCrashInfo | null;
}

WebViewCrashPluginConfig

export interface WebViewCrashPluginConfig {
  /**
   * Restart the WebView from native code when the renderer process dies.
   *
   * @default true
   */
  restartOnCrash?: boolean;

  /**
   * Fixed native interval, in milliseconds, for proactively replacing long-running WebViews.
   *
   * Set to `0` to disable interval restarts. Do not combine an active interval
   * with `restartCron`; native initialization fails fast when both schedules are configured.
   *
   * @default 0
   */
  restartIntervalMs?: number;

  /**
   * Cron schedule for proactively replacing long-running WebViews.
   *
   * Uses standard 5-field cron syntax in the device local timezone:
   * `minute hour day-of-month month day-of-week`.
   *
   * Examples:
   * - `0 3 * * *` restarts every day at 03:00.
   * - `0,30 * * * *` restarts every 30 minutes.
   *
   * Do not combine this with an active `restartIntervalMs`; native initialization
   * fails fast when both schedules are configured.
   */
  restartCron?: string;

  /**
   * Delay, in milliseconds, before restarting after a crash.
   *
   * @default 0
   */
  restartAfterCrashDelayMs?: number;
}

WebViewCrashInfo

export interface WebViewCrashInfo {
  /**
   * Platform that detected and stored the marker.
   */
  platform: WebViewCrashPlatform;

  /**
   * Unix timestamp in milliseconds for when the marker was written.
   */
  timestamp: number;

  /**
   * ISO-8601 version of `timestamp`.
   */
  timestampISO: string;

  /**
   * Platform-specific reason for the crash or restart marker.
   */
  reason: WebViewCrashReason;

  /**
   * Last known WebView URL when the marker was written.
   */
  url?: string;

  /**
   * Android-only hint from `RenderProcessGoneDetail.didCrash()`.
   */
  didCrash?: boolean;

  /**
   * Android-only renderer priority reported at exit.
   */
  rendererPriorityAtExit?: number;

  /**
   * iOS-only application state captured when the WebView process died.
   */
  appState?: WebViewCrashAppState;
}

WebViewCrashPlatform

export type WebViewCrashPlatform = 'android' | 'ios' | 'web';

WebViewCrashReason

export type WebViewCrashReason =
  | 'renderProcessGone'
  | 'webContentProcessDidTerminate'
  | 'periodicRestart'
  | 'manualRestart'
  | 'simulated';

WebViewCrashAppState

export type WebViewCrashAppState = 'active' | 'inactive' | 'background' | 'unknown';

Quelle der Wahrheit

Diese Seite wird aus dem Plugin generiert. src/definitions.tsRe-run the sync when the public API changes upstream.

Weitermachen von Getting Started

Wenn Sie "Getting Started" verwenden, um native Medien und Schnittstellenverhalten zu planen, verbinden Sie es mit "Using @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-webview-crash" für die native Fähigkeit in "Using @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-webview-crash", "Using @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-live-activities" für die native Fähigkeit in "Using @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-live-activities", "@capgo/capacitor-live-activities" für die Implementierungsdetails in "@capgo/capacitor-live-activities", "Using @capgo/capacitor-video-player" für die native Fähigkeit in "Using @capgo/capacitor-video-player", und "@capgo/capacitor-webview-crash" für die native Fähigkeit in "@capgo/capacitor-webview-crash" "@capgo/capacitor-live-activities" für die native Fähigkeit in "@capgo/capacitor-live-activities" "@capgo/capacitor-video-player" für die native Fähigkeit in "@capgo/capacitor-video-player" "@capgo/capacitor-live-activities" für die native Fähigkeit in "@capgo/capacitor-live-activities" "@capgo/capacitor-live-activities" für die native Fähigkeit in "@capgo/capacitor-live-activities" "@capgo/capacitor-live-activities" für die native Fähigkeit in "@capgo/capacitor-live-activities" @capgo/capacitor-video-player für die Implementierungsdetails in @capgo/capacitor-video-player.