Mulai Dari Getting Started

Instalasi

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

Impor

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

Alur pemulihan yang disarankan

Tetapkan pemanggil sebagai awal mungkin dalam proses startup aplikasi Anda, sehingga 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 ulang mulai di capacitor.config.ts agar keputusan tetap di native code meskipun 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 membuka WebView yang sama selama hari-hari: layar kiosk, dashboard kontrol ruang, scanner gudang, terminal kasir, tablet armada, dan tanda digital. Gunakan restartCron untuk ulang mulai jam dinding seperti 0 3 * * * untuk ulang mulai harian pukul 03:00 di zona waktu lokal perangkat. Ulang mulai yang direncanakan menulis tanda marker yang menunggu reason: 'periodicRestart', kemudian Android merekreasi aktivitas host dan iOS membangun kembali jembatan Capacitor view sehingga Capacitor baru dibuat dari native Capacitor. WKWebView is created from native code.

Pilih interval atau jadwal cron yang produk Anda dapat menolerir. restartCron supports *, daftar, rentang, dan langkah. Jangan konfigurasi kedua jadwal sekaligus: inisialisasi asli mengeluarkan kesalahan konfigurasi fatal ketika restartCron dijadwalkan dan restartIntervalMs lebih besar dari 0. Restart membuat runtime JavaScript baru, jadi simpan event yang ditunda, status formulir yang belum disimpan, dan status navigasi saat ini sebelum menggunakan jadwal agresif.

Pemulihan Otomatis

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

await WebViewCrash.restartWebView();

Methode menulis marker yang ditunggu dengan reason: 'manualRestart'menyelesaikan panggilan saat ini, kemudian meminta code asli untuk membuat WebView yang segar. Android merekonstruksi aktivitas host. iOS merekonstruksi jembatan Capacitor view sehingga halaman baru WKWebView membuat halaman baru bukan memuat halaman saat ini.

Ringkasan API

getPendingCrashInfo

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

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

clearPendingCrashInfo

Menghapus marker yang disimpan setelah Anda selesai menangani pemulihan.

await WebViewCrash.clearPendingCrashInfo();

simulateCrashRecovery

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

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 rendererPriorityAtExit ketika platform menyediakan mereka.
• iOS menyimpan metadata kecelakaan dari webViewWebContentProcessDidTerminate dan menambahkan keadaan aplikasi saat ini ketika tersedia.
• Manual dan restart yang dijadwalkan membuat WebView yang segar. Android merefresh aktivitas host; iOS merefresh jendela bridge Capacitor.
• Restart yang dijadwalkan menggunakan reason: 'periodicRestart'; restart manual menggunakan reason: 'manualRestart'.
• Web tidak mendeteksi kecelakaan renderer yang sebenarnya. Implementasi web hanya meniru perilaku dengan penyimpanan lokal.

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

Halaman ini dihasilkan dari plugin’s src/definitions.ts. Re-run sync ketika API publik berubah di atas.

Teruskan dari Getting Started

Jika Anda menggunakan Getting Started untuk merencanakan perilaku media dan interface 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 native di Menggunakan @capgo/capacitor-video-player, dan @capgo/capacitor-player video untuk detail implementasi di @capgo/capacitor-player video.