Per iniziare
Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.
Set up this Capacitor plugin in the project.
Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-webview-crash`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/webview-crash/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.
Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:
bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-pluginsPoi usa il seguente prompt:
Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-webview-crash` plugin in my project.Se preferisci la configurazione manuale, installa il plugin eseguendo questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:
bun add @capgo/capacitor-webview-crashbunx cap syncImporta
Sezione intitolata “Import”import { WebViewCrash } from '@capgo/capacitor-webview-crash';Avvio rapido
Sezione intitolata “Quick start”import { WebViewCrash } from '@capgo/capacitor-webview-crash';
const result = await WebViewCrash.getPendingCrashInfo();console.log(result);Esempio: clearPendingCrashInfo
Sezione intitolata “Esempio: clearPendingCrashInfo”import { WebViewCrash } from '@capgo/capacitor-webview-crash';
await WebViewCrash.clearPendingCrashInfo();Esempio: simulateCrashRecovery
Sezione intitolata “Esempio: simulateCrashRecovery”import { WebViewCrash } from '@capgo/capacitor-webview-crash';
const result = await WebViewCrash.simulateCrashRecovery();console.log(result);Errori comuni
Sezione intitolata “Errori comuni”- Listener: rimuovi gli handle quando gli schermi vengono smontati.
- Sync nativo: esegui
bunx cap syncdopo gli aggiornamenti dei plugin. - Fonte di verità: fidati
src/definitions.tsnel repo GitHub.
Flusso di recovery consigliato
Sezione intitolata “Flusso di recupero consigliato”Aggiungi i listener il prima possibile durante l'avvio dell'app, in modo che il runtime recuperato possa reagire prima che gli utenti continuino a navigare:
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);}Riavvio automatico nativo
Sezione intitolata “Riavvio automatico nativo”Imposta le opzioni di riavvio in capacitor.config.ts così la decisione resta nel codice nativo code anche se il runtime JavaScript è in crash o non è ancora caricato:
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;Usa restartIntervalMs per le app always-on in cui gli utenti potrebbero mantenere la stessa WebView aperta per giorni: schermi kiosk, dashboard di sala controllo, scanner di magazzino, terminali POS, tablet di flotta e digital signage. Usa restartCron per i riavvii basati sull'orologio reale, come 0 3 * * * per un riavvio giornaliero alle 03:00 nel fuso orario locale del dispositivo. I riavvii programmati scrivono un marker pendente con reason: 'periodicRestart', quindi Android ricrea l'activity host e iOS ricostruisce la view bridge Capacitor in modo che un nuovo WKWebView venga creato dal nativo code.
Scegli un intervallo o una pianificazione cron che il tuo prodotto possa tollerare. restartCron supporta *, elenchi, intervalli e step. Non configurare entrambe le pianificazioni contemporaneamente: l'inizializzazione nativa genera un errore di configurazione fatale quando restartCron è impostato e restartIntervalMs è maggiore di 0. Un restart crea un nuovo runtime JavaScript: salva gli eventi in coda, lo stato non salvato dei form e lo stato di navigazione corrente prima di usare schedule aggressivi.
Riavvio nativo manuale
Sezione intitolata “Riavvio nativo manuale”Chiama restartWebView() quando il runtime JavaScript corrente decide che la WebView nativa deve essere sostituita proattivamente, ad esempio dopo un workflow ad alto consumo di memoria o prima di entrare in una sessione lunga non supervisionata:
await WebViewCrash.restartWebView();Il metodo scrive un marker pendente con reason: 'manualRestart', risolve la chiamata corrente, poi chiede a code nativo di creare una nuova WebView. Android ricrea l'activity host. iOS ricostruisce la view bridge Capacitor in modo che una nuova WKWebView viene creata invece di ricaricare la pagina corrente.
Panoramica di API
Sezione intitolata “Panoramica di API”getPendingCrashInfo
Sezione intitolata “getPendingCrashInfo”Restituisce il marker salvato di crash nativo o riavvio, oppure null quando non c'è nulla in sospeso.
const pending = await WebViewCrash.getPendingCrashInfo();if (pending.value) { console.log(pending.value.platform, pending.value.reason);}clearPendingCrashInfo
Sezione intitolata “clearPendingCrashInfo”Cancella il marker salvato dopo che la gestione del recupero è terminata.
await WebViewCrash.clearPendingCrashInfo();simulateCrashRecovery
Sezione intitolata “simulateCrashRecovery”Crea un marker di crash fittizio in modo che QA e debug locale possano testare il percorso di recupero senza far crashare un WebView reale.
const simulated = await WebViewCrash.simulateCrashRecovery();console.log(simulated.value);restartWebView
Sezione intitolata “restartWebView”Salva un marker di riavvio manuale e chiede a code nativo di creare un nuovo WebView.
await WebViewCrash.restartWebView();Note sulla piattaforma
Sezione intitolata “Note sulla piattaforma”- Android salva i metadati del crash da
onRenderProcessGone, tra cuididCrasherendererPriorityAtExitquando la piattaforma li fornisce. - iOS archivia i metadati di crash da
webViewWebContentProcessDidTerminatee aggiunge lo stato corrente dell'applicazione quando disponibile. - I riavvii manuali e programmati creano una nuova WebView. Android ricrea l'activity host; iOS ricostruisce la view bridge Capacitor.
- I riavvii programmati usano
reason: 'periodicRestart'; i riavvii manuali usanoreason: 'manualRestart'. - Web non rileva i crash reali del renderer. L'implementazione web simula solo il comportamento con lo storage locale.
Riferimento tipi
Sezione intitolata “Riferimento ai tipi”PendingCrashInfoResult
Sezione intitolata “PendingCrashInfoResult”export interface PendingCrashInfoResult { /** * Stored crash or restart metadata, or `null` when no marker is pending. */ value: WebViewCrashInfo | null;}WebViewCrashPluginConfig
Sezione intitolata “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
Sezione intitolata “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
Sezione intitolata “WebViewCrashPlatform”export type WebViewCrashPlatform = 'android' | 'ios' | 'web';WebViewCrashReason
Sezione intitolata “WebViewCrashReason”export type WebViewCrashReason = | 'renderProcessGone' | 'webContentProcessDidTerminate' | 'periodicRestart' | 'manualRestart' | 'simulated';WebViewCrashAppState
Sezione intitolata “WebViewCrashAppState”export type WebViewCrashAppState = 'active' | 'inactive' | 'background' | 'unknown';Fonte di verità
Sezione intitolata “Fonte di verità”Questa pagina è generata dal src/definitions.ts. Riesegui la sync quando il API pubblico cambia upstream.
Continua da Getting Started
Sezione intitolata “Continua da Getting Started”Se stai usando Per iniziare per pianificare il comportamento dei media nativi e dell'interfaccia, collegalo a Usare @capgo/capacitor-webview-crash per la funzionalità nativa in Using @capgo/capacitor-webview-crash, Uso di @capgo/capacitor-live-activities per la funzionalità nativa nella pagina Uso di @capgo/capacitor-live-activities, @capgo/capacitor-live-activities per il dettaglio implementativo in @capgo/capacitor-live-activities, Uso di @capgo/capacitor-video-player per la funzionalità nativa nella pagina Uso di @capgo/capacitor-video-player, e @capgo/capacitor-video-player per il dettaglio implementativo in @capgo/capacitor-video-player.