Getting Started

Installieren

Sie können unser AI-gestütztes Setup verwenden, um das Plugin zu installieren. Fügen Sie die Capgo-Fähigkeiten Ihrem AI-Tool mit folgendem Befehl hinzu:

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

Verwenden Sie dann die folgende Anweisung:

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

Wenn Sie die manuelle Einrichtung bevorzugen, installieren Sie das Plugin, indem Sie die folgenden Befehle ausführen und die unten angegebenen Plattform-spezifischen Anweisungen befolgen:

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

Importieren

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

Empfohlene Wiederherstellungsablauf

Fügen Sie Listener so früh wie möglich in Ihrem Anwendungsstart hinzu, 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);
}

Native Auto-Neustart

Neustartoptionen in capacitor.config.ts damit die Entscheidung im native code bleibt, selbst wenn der JavaScript-Interpreter 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 für Apps, die immer eingeschaltet sind, bei denen die Benutzer den gleichen WebView über Tage hinweg offen halten können: Kiosk-Screens, Steuerungszentralen, Lager-Scannern, POS-Terminals, Flotten-Tablets und digitale Anzeigetafeln. restartCron für Wiederholungsneustarts wie 0 3 * * * für einen täglichen Neustart um 03:00 Uhr in der lokalen Gerätegaufarbeitszeitzone. Geplante Neustarts schreiben einen wartenden Marker mit reason: 'periodicRestart', dann wird Android die Hostaktivität neu erstellen und iOS die Capacitor-Brückeansicht neu erstellen, sodass ein neuer WKWebView aus dem native code erstellt wird.

Wählen Sie einen Zeitraum oder eine Cron-Auftragsplanung, den Ihr Produkt tolerieren kann. restartCron unterstützt *, Listen, Ränge und Schritte. Konfigurieren Sie beide Schedules nicht 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 persistieren Sie die in der Warteschlange stehenden Ereignisse, ungelesene Formulardaten und den aktuellen Navigationszustand, bevor Sie aggressive Schedules verwenden.

Manueller native Neustart

Aufrufen restartWebView() wenn der aktuelle JavaScript-Runtime entscheidet, dass der native WebView vorzeitig ersetzt werden sollte, zum Beispiel nach einem memory-intensiven Workflow oder vor dem Eingehen einer langen unbesetzten Sitzung:

await WebViewCrash.restartWebView();

Die Methode schreibt einen wartenden Marker mit reason: 'manualRestart', löst die aktuelle Anrufung auf und fragt den native code nach, um eine frische WebView zu erstellen. Android reaktualisiert die Hostaktivität. iOS reaktualisiert die Capacitor Bridgeansicht, sodass eine neue WKWebView wird erstellt anstatt die aktuelle Seite neu zu laden.

API Übersicht

getPendingCrashInfo

Gibt den gespeicherten native Crash- oder Neustartmarker zurück, oder null wenn nichts ansteht.

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-Handling.

await WebViewCrash.clearPendingCrashInfo();

simulateCrashRecovery

Erstellt einen fiktiven Crashmarker, damit QA und lokale Debugging 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 bittet das native code um die Erstellung eines frischen WebViews.

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 wiederholt die Capacitor Brückensicht.
• Geplante Neustarts verwenden reason: 'periodicRestart'manuelle Neustarts verwenden reason: 'manualRestart'.
• Web erkennt keine echten Renderer-Crashes. Die Web-Implementierung simuliert nur das Verhalten mit lokalem 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 wurde aus dem Plugin generiert. src/definitions.tsRe-run the sync wenn die öffentliche API upstream ändert.

Weitermachen von Getting Started

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