Mulai

Instalasi

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

Impor

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

Alur pemulihan yang direkomendasikan

Pasang pemangku jawab sebagai cepat mungkin dalam proses startup aplikasi Anda agar runtime yang dipulihkan dapat bereaksi sebelum pengguna melanjutkan navigasi:

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);
}

Mulai ulang otomatis native

Atur opsi restart di capacitor.config.ts agar keputusan tetap di native code bahkan ketika runtime JavaScript telah gagal atau belum dimuat:

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;

Gunakan restartIntervalMs untuk aplikasi selalu aktif di mana pengguna mungkin menjaga WebView yang sama terbuka selama hari-hari: layar kiosk, dashboard kontrol ruang, scanner gudang, terminal kasir, tablet armada, dan tanda digital. Gunakan restartCron untuk restart jam dinding seperti 0 3 * * * untuk restart harian pada pukul 03:00 dalam zona waktu perangkat lokal. Restart yang dijadwalkan menulis marker yang menunggu dengan reason: 'periodicRestart', kemudian Android merekreasi aktivitas host dan iOS membangun ulang jendela bridge Capacitor sehingga Capacitor baru WKWebView dibuat dari native code.

Pilih interval atau skedul cron yang produk Anda dapat menanggung. restartCron mendukung *, daftar, rentang, dan langkah. Jangan konfigurasi kedua skedul sekaligus: inisialisasi native melemparkan kesalahan konfigurasi fatal ketika restartCron diatur dan restartIntervalMs lebih besar dari 0. Restart menciptakan runtime JavaScript yang segar, jadi simpan event yang ditunggu, status formulir yang belum disimpan, dan status navigasi saat ini sebelum menggunakan skedul agresif.

Restart native manual

Panggil restartWebView() ketika runtime JavaScript saat ini memutuskan bahwa WebView native harus diganti secara proaktif, misalnya setelah alur kerja berat memori atau sebelum memasuki sesi tidak terduga yang panjang:

await WebViewCrash.restartWebView();

Metode menulis marker yang menunggu dengan __CAPGO_KEEP_0__, reason: 'manualRestart'mengatasi panggilan saat ini, kemudian bertanya kepada native code untuk membuat WebView baru yang segar. Android merekreasikan aktivitas host. iOS merekonstruksi jembatan Capacitor view sehingga halaman baru WKWebView dibuat daripada memuat halaman saat ini.

API ringkasan

getPendingCrashInfo

Mengembalikan marker kecelakaan atau restart yang disimpan secara native, atau null ketika tidak ada yang menunggu.

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

clearPendingCrashInfo

Membersihkan marker yang disimpan setelah proses pemulihan Anda selesai.

await WebViewCrash.clearPendingCrashInfo();

simulateCrashRecovery

Membuat marker kecelakaan palsu sehingga QA dan debugging lokal dapat menguji jalur pemulihan tanpa membuat WebView nyata mengalami kecelakaan.

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

restartWebView

Menyimpan marker restart manual dan meminta native code untuk membuat WebView segar.

await WebViewCrash.restartWebView();

Catatan platform

• Android menyimpan metadata kecelakaan dari onRenderProcessGone, termasuk didCrash dan ketika platform menyediakan mereka. rendererPriorityAtExit iOS menyimpan metadata kejadian crash dari
• dan menambahkan keadaan aplikasi saat ini ketika tersedia. webViewWebContentProcessDidTerminate Pemulihan manual dan yang dijadwalkan membuat WebView yang segar. Android merekreasikan aktivitas host; iOS membangun ulang jembatan view __CAPGO_KEEP_0__.
• Manual and scheduled restarts create a fresh WebView. Android recreates the host activity; iOS rebuilds the Capacitor bridge view.
• ; pemulihan manual menggunakan reason: 'periodicRestart'Web tidak mendeteksi crash renderer yang sebenarnya. Implementasi web hanya meniru perilaku dengan menggunakan penyimpanan lokal. reason: 'manualRestart'.
• Referensi Tipe

Bab berjudul “Referensi Tipe”

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

Sumber Kebenaran

This page is generated from the plugin’s src/definitions.tsRe-run the sync when the public API changes upstream.

Teruskan dari Getting Started

Jika Anda menggunakan Getting Started untuk merencanakan perilaku media dan antarmuka native, hubungkannya dengan Menggunakan @capgo/capacitor-webview-crash untuk kemampuan native di Menggunakan @capgo/capacitor-webview-crash, Menggunakan @capgo/capacitor-live-activities untuk kemampuan native di Menggunakan @capgo/capacitor-live-activities, @capgo/capacitor-live-activities untuk detail implementasi di @capgo/capacitor-live-activities, Menggunakan @capgo/capacitor-video-player untuk kemampuan asli di Menggunakan @capgo/capacitor-video-player, dan @capgo/capacitor-video-player untuk detail implementasi di @capgo/capacitor-video-player.