Getting Started

Installieren

Sie können unser AI-gestütztes Setup verwenden, um das Plugin zu installieren. Fügen Sie den Capgo-Fähigkeiten Ihrer AI-Anwendung mit dem folgenden 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 darunter 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 Ihrer App-Startzeit ein, damit das wiederhergestellte Laufzeitumfeld 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

Setzen Sie Neustartoptionen in capacitor.config.ts Die Entscheidung bleibt im native code auch dann, 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;

Use restartIntervalMs für Apps, die immer eingeschaltet sind, bei denen Benutzer den gleichen WebView über Tage hinweg offen halten können: Kiosk-Screens, Steuerungszentralen, Lager-Scannern, POS-Terminals, Flotten-Tablets und digitale Anzeigen. Verwenden Sie restartCron für Uhrzeiten-Neustarts wie 0 3 * * * für einen täglichen Neustart um 03:00 Uhr in der lokalen Gerätezeitzone. 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, damit ein neuer WKWebView wird aus nativen code erstellt.

Wählen Sie einen Zeitraum oder eine Cron-Aufgabenplanung, die Ihr Produkt ertragen kann. restartCron unterstützt *, Listen, Ränge und Schritte. Konfigurieren Sie nicht beide Schedules gleichzeitig: Die native Initialisierung wirft bei einer fatalen Konfigurationsfehler, wenn restartCron festgelegt ist und restartIntervalMs ist größer als 0ist. Ein Neustart erstellt einen frischen JavaScript-Runtime, also persistieren Sie die angesammelten 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 bevor eine lange unbesetzte Sitzung beginnt:

await WebViewCrash.restartWebView();

Die Methode schreibt einen wartenden Marker mit reason: 'manualRestart', löst die aktuelle Anfrage auf, und fragt dann das native code an, um eine frische WebView zu erstellen. Android reaktiviert die Hostaktivität. iOS rekonstruiert die Capacitor Bridgeansicht, so dass eine neue WKWebView anstatt der aktuellen Seite neu geladen wird.

API Übersicht

getPendingCrashInfo

Returns die gespeicherte native Crash- oder Neustartmarke, oder null wenn nichts Wartendes ist.

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

clearPendingCrashInfo

Der gespeicherte Marker wird nach Abschluss Ihres Recovery-Handling gelöscht.

await WebViewCrash.clearPendingCrashInfo();

simulateCrashRecovery

Erstellt einen fiktiven Crashmarker, damit QA und lokale Debugging die Wiederherstellungsroute ohne einen 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 Crash-Metadaten von webViewWebContentProcessDidTerminate und fügt den aktuellen Anwendungsstatus hinzu, wenn verfügbar.
• Manuelle und geplante Neustarts erstellen einen frischen WebView. Android wiederholt die Hostaktivität; iOS wiederholt die Capacitor Bridgeansicht.
• Geplante Neustarts verwenden reason: 'periodicRestart'Manuelle Neustarts verwenden reason: 'manualRestart'.
• Webdetektion von echten Renderer-Crashes funktioniert nicht. Die Webimplementierung 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 wurde von dem Plugin generiert. src/definitions.tsRe-run die Synchronisation, wenn die öffentliche API upstream geändert wird.

Weitermachen von Getting Started

Wenn Sie Capgo verwenden Getting Started um native Medien und Schnittstellenverhalten zu planen, verbinden Sie es mit Mit @capgo/capacitor-webview-crash für die native Fähigkeit in Mit @capgo/capacitor-webview-crash, Mit @capgo/capacitor-live-activities für die native Fähigkeit in Mit @capgo/capacitor-live-activities, @capgo/capacitor-live-aktivitäten für die Implementierungsdetails in @capgo/capacitor-live-activities, Mit @capgo/capacitor-video-player für die native Funktion in @capgo/capacitor-video-player und @capgo/capacitor-Video-Player für die Implementierungsdetail in @capgo/capacitor-video-player.