Vai al contenuto

Per iniziare

GitHub

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:

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

Poi 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:

Finestra del terminale
bun add @capgo/capacitor-webview-crash
bunx cap sync
import { WebViewCrash } from '@capgo/capacitor-webview-crash';
import { WebViewCrash } from '@capgo/capacitor-webview-crash';
const result = await WebViewCrash.getPendingCrashInfo();
console.log(result);
import { WebViewCrash } from '@capgo/capacitor-webview-crash';
await WebViewCrash.clearPendingCrashInfo();
import { WebViewCrash } from '@capgo/capacitor-webview-crash';
const result = await WebViewCrash.simulateCrashRecovery();
console.log(result);
  • Listener: rimuovi gli handle quando gli schermi vengono smontati.
  • Sync nativo: esegui bunx cap sync dopo gli aggiornamenti dei plugin.
  • Fonte di verità: fidati src/definitions.ts nel repo GitHub.

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

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.

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.

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

Cancella il marker salvato dopo che la gestione del recupero è terminata.

await WebViewCrash.clearPendingCrashInfo();

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

Salva un marker di riavvio manuale e chiede a code nativo di creare un nuovo WebView.

await WebViewCrash.restartWebView();
  • Android salva i metadati del crash da onRenderProcessGone, tra cui didCrash e rendererPriorityAtExit quando la piattaforma li fornisce.
  • iOS archivia i metadati di crash da webViewWebContentProcessDidTerminate e 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 usano reason: 'manualRestart'.
  • Web non rileva i crash reali del renderer. L'implementazione web simula solo il comportamento con lo storage locale.
export interface PendingCrashInfoResult {
/**
* Stored crash or restart metadata, or `null` when no marker is pending.
*/
value: WebViewCrashInfo | null;
}
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;
}
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;
}
export type WebViewCrashPlatform = 'android' | 'ios' | 'web';
export type WebViewCrashReason =
| 'renderProcessGone'
| 'webContentProcessDidTerminate'
| 'periodicRestart'
| 'manualRestart'
| 'simulated';
export type WebViewCrashAppState = 'active' | 'inactive' | 'background' | 'unknown';

Questa pagina è generata dal src/definitions.ts. Riesegui la sync quando il API pubblico cambia upstream.

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.