Getting Started

Installieren

Sie können unsere AI-gestützte Einrichtung verwenden, um den Plugin zu installieren. Fügen Sie die Capgo-Fähigkeiten zu Ihrem AI-Tool hinzu, indem Sie die folgende Befehl ausführen:

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

Verwenden Sie dann den folgenden Prompt:

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 folgen Sie den Plattform-spezifischen Anweisungen unten:

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

Importieren

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

Empfohlener Wiederherstellungsfluss

Fügen Sie Hörer so früh wie möglich in Ihrer Anwendungsstartzeit ein, damit das wiederhergestellte Laufzeitumfeld reagieren kann, bevor die Benutzer 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);
}

Native Auto-Neustart

Setzen Sie Neustartoptionen in capacitor.config.ts so dass 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 für Apps, die immer eingeschaltet sind und bei denen die Benutzer den WebView für Tage offen halten können: Kiosk-Anzeigen, Steuerungszentralen, Lager-Scannern, POS-Terminals, Flotten-Tablets und digitale Schilder. Verwenden Sie restartCron für Uhrzeiten wie 0 3 * * * für einen täglichen Neustart um 03:00 Uhr in der lokalen Geräetzonenzeit. Geplante Neustarts schreiben einen Wartepunkt mit reason: 'periodicRestart'dann wird das Host-Activity von Android neu erstellt und iOS rekonstruiert die Capacitor-Brückeansicht, sodass ein neuer WKWebView erzeugt wird, der aus nativen code-Ressourcen besteht.

Wählen Sie einen Zeitraum oder eine Cron-Schrittfolge, die Ihr Produkt aushalten 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-Objekt, daher müssen Sie vor der Verwendung aggressiver Schedules die angesammelten Ereignisse, ungelesene Formulardaten und die aktuelle Navigationssitzung persistieren.

Händliche native Neustart

Aufrufen restartWebView() Wenn der aktuelle JavaScript- Runtime entscheidet, dass der native WebView vorzeitig ersetzt werden soll, 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 den native code an, um einen frischen WebView zu erstellen. Android reaktivierte die Hostaktivität. iOS rekonstruiert die Capacitor Bridgeansicht, sodass stattdessen eine neue WKWebView stattdessen die aktuelle Seite neu lädt.

API Übersicht

getPendingCrashInfo

Die Methode gibt den gespeicherten native Crash- oder Neustartmarker zurück, oder null wenn nichts anhängig ist.

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

await WebViewCrash.clearPendingCrashInfo();

simulateCrashRecovery

Erstellt einen fiktiven Crashmarker, damit QA und lokale Debugging die Wiederherstellungsroute ohne einen echten WebView zu beenden können.

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

restartWebView

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

await WebViewCrash.restartWebView();

Plattformhinweise

• Android speichert Metadaten zu Crashes von onRenderProcessGone, einschließlich didCrash und rendererPriorityAtExit wenn die Plattform sie bereitstellt.
• iOS speichert Metadaten zu Crashes von webViewWebContentProcessDidTerminate und fügt den aktuellen Anwendungsstatus hinzu, wenn verfügbar.
• Manuelle und geplante Neustarts erstellen einen frischen WebView. Android reaktualisiert die Hostaktivität; iOS rekonstruiert die Capacitor Bridgeansicht.
• Geplante Neustarts verwenden reason: 'periodicRestart'; manuelle Neustarts verwenden reason: 'manualRestart'.
• Webdetektion von echten Renderer-Crashes funktioniert nicht. Die Webimplementierung simuliert das Verhalten mit lokalem Speicher.

Typenreferenz

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 die Synchronisation, wenn die öffentliche API upstream geändert wird.

Weitermachen von Getting Started

Wenn Sie native Medien und Schnittstellenverhalten planen, verbinden Sie es mit Getting Started für die native Fähigkeit in Using @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-webview-crash für die native Fähigkeit in Using @capgo/capacitor-webview-crash für die native Fähigkeit in Using @capgo/capacitor-webview-crash Mit @capgo/capacitor-live-aktivitäten für die native Fähigkeit in Mit @capgo/capacitor-live-aktivitäten @capgo/capacitor-live-aktivitäten für die Implementierungsdetail 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 Implementierungsdetail in @capgo/capacitor-video-player