Getting Started

Installieren

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

Importieren

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

Empfehlenswertes Wiederherstellungsverfahren

Hängen Sie Listener so früh wie möglich in Ihrem Anwendungsstart ein, damit der wiederhergestellte Laufzeitumgebung 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);
}

Native Auto-Wiederstart

Setzen Sie Wiederstartoptionen in capacitor.config.ts damit die Entscheidung im native code bleibt, selbst wenn die JavaScript-Laufzeit abgestürzt ist oder noch 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 Sie restartIntervalMs zur immer-eingeschalteten Apps, bei denen Benutzer möglicherweise den gleichen WebView über Tage hinweg offen halten: Kiosk-Screens, Steuerungszentralen, Lager-Scannern, POS-Terminals, Flotten-Tablets und digitale Anzeigen. Verwenden Sie restartCron zur Wiederstarten nach einer bestimmten Zeit, wie z.B. 0 3 * * * Wiederholen Sie die Anwendung alle __CAPGO_KEEP_0__ Tage in der lokalen Zeitzone um 03:00 Uhr. reason: 'periodicRestart', dann wird die Android-App die Hostaktivität neu erstellen und iOS die Capacitor-Brückensicht neu erstellen, sodass eine neue WKWebView erstellt wird, die von der nativen code-Anwendung gesteuert wird.

Wählen Sie einen Zeitraum oder eine Cron-Auftragskette, die Ihr Produkt tolerieren kann. restartCron Unterstützt *, Listen, Ränge und Schritte. Konfigurieren Sie nicht beide Schedules gleichzeitig: Die native Initialisierung wirft einen fatalen Konfigurationsfehler, wenn restartCron festgelegt ist und restartIntervalMs größer als 0ist. Ein Neustart erstellt ein frisches JavaScript- Runtime, also speichern Sie vor dem Einsatz aggressiver Schedules die angesammelten Ereignisse, ungelesene Formulardaten und den aktuellen Navigationszustand.

Manuelle native Neustart

Aufrufen restartWebView() Wenn der aktuelle JavaScript- Runtime entscheidet, dass die native WebView vorab ersetzt werden sollte, zum Beispiel nach einem memory-intensiven Workflow oder bevor eine lange unbesetzte Sitzung beginnt:

await WebViewCrash.restartWebView();

Die Methode schreibt einen vorläufigen Marker mit reason: 'manualRestart', löst die aktuelle Anfrage auf, fragt dann die native code an, um eine frische WebView zu erstellen. Android reaktivierte die Hostaktivität. iOS rekonstruiert die Capacitor Bridgeansicht, sodass eine neue WKWebView anstatt die aktuelle Seite neu zu laden.

API Übersicht

getPendingCrashInfo

Gibt die gespeicherte native Crash- oder Neustartmarker zurück, oder null wenn nichts vorliegt.

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

clearPendingCrashInfo

Löscht den gespeicherten Marker nach Abschluss Ihrer Recovery-Verarbeitung.

await WebViewCrash.clearPendingCrashInfo();

simulateCrashRecovery

Erstellt einen fiktiven Crash-Marker, damit QA und lokale Debugging die Recovery-Pfad ohne Absturz eines echten WebView ausüben können.

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

restartWebView

Speichert einen manuellen Neustart-Marker und fragt den native code an, einen frischen WebView zu erstellen.

await WebViewCrash.restartWebView();

Plattformhinweise

• Android speichert Crash-Metadaten von onRenderProcessGone, einschließlich didCrash und wenn die Plattform sie bereitstellt. rendererPriorityAtExit iOS speichert Crash-Metadaten von
• und fügt den aktuellen Anwendungsstatus hinzu, wenn verfügbar. webViewWebContentProcessDidTerminate Manuelle und geplante Neustarts erstellen einen frischen WebView. Android reaktualisiert die Hostaktivität; iOS reaktualisiert die __CAPGO_KEEP_0__ Bridgeansicht.
• Manual and scheduled restarts create a fresh WebView. Android recreates the host activity; iOS rebuilds the Capacitor bridge view.
• ; manuelle Neustarts verwenden reason: 'periodicRestart'Web erkennt keine echten Renderer-Crashes. Die Web-Implementierung simuliert nur das Verhalten mit lokalen Speicher. reason: 'manualRestart'.
• Typenverweis

Abschnitt mit dem Titel „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 wurde aus dem Plugin generiert. src/definitions.ts. Wiederholen Sie die Synchronisierung, wenn die öffentliche API upstream geändert wird.

Weitergehen Sie von Getting Started

Wenn Sie native Medien und Schnittstellenverhalten planen, verbinden Sie es mit Mit @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-webview-crash für die native Fähigkeit in Mit @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-webview-crash, Mit @capgo/capacitor-live-activities für die native Fähigkeit in Mit @capgo/capacitor-live-activities, @capgo/capacitor-live-activities for the native capability in Using @capgo/capacitor-live-activities, @capgo/capacitor-live-activities für die Implementierungsdetails in @capgo/capacitor-live-aktivitäten, Mit @capgo/capacitor-video-player für die native Fähigkeit in Mit @capgo/capacitor-video-player, und @capgo/capacitor-video-player für die Implementierungsdetails in @capgo/capacitor-video-player.