Panduan Memulai

Instal

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda menggunakan command berikut:

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

Kemudian gunakan prompt berikut:

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

Jika Anda lebih memilih Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti petunjuk khusus platform di bawah ini:

bun add @capgo/capacitor-webview-crash
bunx cap sync

Impor

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

Mulai cepat

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

const result = await WebViewCrash.getPendingCrashInfo();
console.log(result);

Contoh: clearPendingCrashInfo

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

await WebViewCrash.clearPendingCrashInfo();

Contoh: simulateCrashRecovery

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

const result = await WebViewCrash.simulateCrashRecovery();
console.log(result);

Kesalahan umum

• Listeners: hapus handle saat screen unmount.
• Sinkronisasi Native: jalankan bunx cap sync setelah upgrade plugin.
• Sumber kebenaran tunggal: percayai src/definitions.ts di repo GitHub.

Alur recovery yang direkomendasikan

Pasang listener sedini mungkin saat startup aplikasi agar runtime yang pulih 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);
}

Restart otomatis native

Atur opsi restart di capacitor.config.ts jadi keputusan tetap ada di code native bahkan saat JavaScript runtime crash 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 yang selalu aktif di mana pengguna mungkin membuka WebView yang sama selama berhari-hari: layar kiosk, dashboard ruang kontrol, pemindai gudang, terminal POS, tablet armada, dan digital signage. Gunakan restartCron untuk restart berdasarkan waktu tertentu seperti 0 3 * * * untuk restart harian jam 03:00 di zona waktu lokal perangkat. Scheduled restart akan menulis marker pending dengan reason: 'periodicRestart', lalu Android membuat ulang host activity dan iOS membangun ulang Capacitor bridge view sehingga Capacitor baru WKWebView dibuat dari native code.

Pilih interval atau jadwal cron yang dapat ditoleransi produk Anda. restartCron mendukung *, list, range, dan step. Jangan konfigurasi kedua jadwal sekaligus: inisialisasi native akan memicu fatal config error saat restartCron diatur dan restartIntervalMs lebih besar dari 0. Restart akan membuat runtime JavaScript baru, jadi simpan antrean event, state form yang belum tersimpan, dan state navigasi saat ini sebelum menggunakan jadwal yang agresif.

Restart native secara manual

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

await WebViewCrash.restartWebView();

Metode ini menulis penanda pending dengan reason: 'manualRestart', menyelesaikan panggilan saat ini, lalu meminta native code untuk membuat WebView baru. Android membuat ulang host activity. iOS membangun ulang Capacitor bridge view sehingga WKWebView baru dibuat alih-alih memuat ulang halaman saat ini.

Ikhtisar API

getPendingCrashInfo

Mengembalikan marker crash native atau restart yang tersimpan, atau null ketika tidak ada yang pending.

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

clearPendingCrashInfo

Menghapus marker yang tersimpan setelah proses recovery selesai.

await WebViewCrash.clearPendingCrashInfo();

simulateCrashRecovery

Membuat fake crash marker agar QA dan debugging lokal bisa mencoba alur recovery tanpa harus crash WebView asli.

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

restartWebView

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

await WebViewCrash.restartWebView();

Catatan platform

• Android menyimpan metadata crash dari onRenderProcessGone, termasuk didCrash dan rendererPriorityAtExit saat platform menyediakannya.
• iOS menyimpan metadata crash dari webViewWebContentProcessDidTerminate dan menambahkan state aplikasi saat ini jika tersedia.
• Restart manual dan terjadwal membuat WebView baru. Android membuat ulang host activity; iOS membangun ulang Capacitor bridge view.
• Restart terjadwal menggunakan reason: 'periodicRestart'; restart manual menggunakan reason: 'manualRestart'.
• Web tidak mendeteksi crash renderer yang sebenarnya. Implementasi web hanya mensimulasikan perilaku tersebut dengan local storage.

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 dibuat dari plugin src/definitions.ts. Jalankan ulang sync saat API publik berubah di upstream.

Lanjutkan dari Getting Started

Jika Anda menggunakan Panduan Memulai untuk merencanakan perilaku media dan antarmuka native, hubungkan dengan Menggunakan @capgo/capacitor-webview-crash untuk kapabilitas native di bagian 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-video-player untuk detail implementasi di @capgo/capacitor-video-player.