Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Nutze dann diesen Prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-webview-crash` plugin in my project.

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

bun add @capgo/capacitor-webview-crash
bunx cap sync

Importieren

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

Quickstart

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

const result = await WebViewCrash.getPendingCrashInfo();
console.log(result);

Beispiel: clearPendingCrashInfo

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

await WebViewCrash.clearPendingCrashInfo();

Beispiel: simulateCrashRecovery

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

const result = await WebViewCrash.simulateCrashRecovery();
console.log(result);

Häufige Stolperfallen

• Listener: Handles beim Unmount der Screens entfernen.
• Nativer Sync: ausführen bunx cap sync nach Plugin-Upgrades.
• Single Source of Truth: Vertrauen src/definitions.ts im GitHub Repo.

Empfohlener Recovery-Flow

Registriere Listener so früh wie möglich beim App-Startup, damit die wiederhergestellte Runtime reagieren kann, bevor Nutzer weiter 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);
}

Nativer Auto-Restart

Konfiguriere die Restart-Optionen in capacitor.config.ts damit die Entscheidung in der nativen code bleibt, selbst wenn die JavaScript-Runtime 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;

Nutzt restartIntervalMs für Always-on-Apps, bei denen Nutzer denselben WebView über Tage offen halten: Kiosk-Displays, Control-Room-Dashboards, Lager-Scanner, POS-Terminals, Flotten-Tablets und Digital Signage. Nutze restartCron für Neustarts zu festen Uhrzeiten wie 0 3 * * * für einen täglichen Neustart um 03:00 Uhr in der lokalen Zeitzone des Geräts. Geplante Restarts schreiben einen Pending-Marker mit reason: 'periodicRestart', dann erstellt Android die Host-Activity neu und iOS baut die Capacitor Bridge-View wieder auf, sodass ein neuer WKWebView aus nativem code erstellt wird.

Wähle ein Intervall oder einen Cron-Zeitplan, den dein Produkt verkraften kann. restartCron unterstützt *, Listen, Bereiche und Schritte. Konfiguriere nicht beide Zeitpläne gleichzeitig: Die native Initialisierung wirft einen fatalen Config-Error, wenn restartCron gesetzt ist und restartIntervalMs ist größer als 0ist. Ein Neustart erstellt eine frische JavaScript-Runtime; speichere also gepufferte Events, ungespeicherte Formularzustände und den aktuellen Navigationszustand, bevor du aggressive Zeitpläne nutzt.

Manueller nativer Neustart

Rufe restartWebView() wenn die aktuelle JavaScript-Runtime entscheidet, dass der native WebView proaktiv ersetzt werden sollte, zum Beispiel nach einem speicherintensiven Workflow oder vor einer langen, unbeaufsichtigten Sitzung:

await WebViewCrash.restartWebView();

Die Methode schreibt ein Pending-Marker mit reason: 'manualRestart', löst den aktuellen Aufruf auf und bittet dann das native code, einen frischen WebView zu erstellen. Android erstellt die Host-Activity neu. iOS baut die Capacitor Bridge-View neu auf, sodass ein neuer WKWebView erstellt wird, anstatt die aktuelle Seite neu zu laden.

API Übersicht

getPendingCrashInfo

Gibt den gespeicherten nativen Crash- oder Neustart-Marker zurück, oder null wenn nichts aussteht.

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

clearPendingCrashInfo

Löscht den gespeicherten Marker, sobald die Fehlerbehebung abgeschlossen ist.

await WebViewCrash.clearPendingCrashInfo();

simulateCrashRecovery

Erzeugt einen Fake-Crash-Marker, damit QA und lokales Debugging den Recovery-Pfad testen können, ohne ein echtes WebView zum Absturz zu bringen.

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

restartWebView

Speichert einen manuellen Restart-Marker und weist das native code an, ein neues WebView zu erstellen.

await WebViewCrash.restartWebView();

Plattform-Hinweise

• Android speichert Crash-Metadaten von onRenderProcessGone, einschließlich didCrash und rendererPriorityAtExit sofern die Plattform diese bereitstellt.
• iOS speichert Crash-Metadaten von webViewWebContentProcessDidTerminate und fügt den aktuellen App-Status hinzu, falls verfügbar.
• Manuelle und geplante Restarts erstellen eine neue WebView. Android erstellt die Host-Activity neu; iOS baut die Capacitor Bridge-View neu auf.
• Geplante Restarts nutzen reason: 'periodicRestart'; manuelle Restarts nutzen reason: 'manualRestart'.
• Web erkennt echte Renderer-Crashes nicht. Die Web-Implementierung simuliert das Verhalten lediglich über den Local Storage.

Typ-Referenz

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';

Source of Truth

Diese Seite wird aus dem Plugin generiert src/definitions.ts. Führe den Sync erneut aus, wenn sich das öffentliche API upstream ändert.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte , um natives Media- und Interface-Verhalten zu planen, verbinde es mit Verwendung von @capgo/capacitor-webview-crash für die native Funktion in der Verwendung von @capgo/capacitor-webview-crash, @capgo/capacitor-live-activities verwenden für die native Funktion in „@capgo/capacitor-live-activities verwenden“, @capgo/capacitor-live-activities für die Implementierungsdetails in @capgo/capacitor-live-activities, Verwendung von @capgo/capacitor-video-player für die native Funktion in „@capgo/capacitor-video-player verwenden“, und @capgo/capacitor-video-player für das Implementierungsdetail in @capgo/capacitor-video-player.