Saltar al contenido

Primeros pasos

GitHub

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

Ventana de terminal
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);
  • Listeners: elimina los handles cuando se desmonten las pantallas.
  • Sync nativo: ejecuta bunx cap sync tras actualizar los plugins.
  • Fuente de verdad: confianza src/definitions.ts en el repo de GitHub.

Adjunta listeners lo antes posible durante el arranque de tu app para que el runtime recuperado pueda reaccionar antes de que los usuarios sigan navegando:

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

Configura las opciones de reinicio en capacitor.config.ts así, la decisión permanece en el code nativo incluso si el runtime de JavaScript ha fallado o aún no se ha cargado:

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 para apps que siempre están activas y donde los usuarios mantienen el mismo WebView abierto por días: kioscos, dashboards de salas de control, scanners de almacén, terminales POS, tablets de flota y señalización digital. Usa restartCron para reinicios a horas fijas como 0 3 * * * para un reinicio diario a las 03:00 en la zona horaria local del dispositivo. Los reinicios programados escriben un marcador pendiente con reason: 'periodicRestart', luego Android recrea la activity host e iOS reconstruye la vista del bridge Capacitor para que una nueva WKWebView a partir del code nativo.

Elige un intervalo o una programación cron que tu producto pueda soportar. restartCron soporta *, listas, rangos y pasos. No configures ambas programaciones a la vez: la inicialización nativa lanza un error fatal de configuración cuando restartCron está configurado y restartIntervalMs es mayor que 0. Un reinicio crea un nuevo entorno de ejecución de JavaScript, así que persiste los eventos en cola, el estado de formularios sin guardar y la navegación actual antes de usar programaciones agresivas.

Llama a restartWebView() cuando el runtime de JavaScript actual decide que el WebView nativo debe reemplazarse de forma proactiva, por ejemplo, tras un flujo de trabajo con alto consumo de memoria o antes de iniciar una sesión larga sin supervisión:

await WebViewCrash.restartWebView();

El método escribe un marcador pendiente con reason: 'manualRestart', resuelve la llamada actual y luego solicita al code nativo que cree un WebView nuevo. Android recrea la actividad host. iOS reconstruye la vista del bridge Capacitor para que se cree un nuevo WKWebView en lugar de recargar la página actual.

Devuelve el marcador almacenado de crash nativo o reinicio, o null cuando no hay nada pendiente.

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

Borra el marcador almacenado una vez finalizado el manejo de la recuperación.

await WebViewCrash.clearPendingCrashInfo();

Crea un marcador de crash simulado para que QA y el debugging local puedan probar la ruta de recuperación sin romper un WebView real.

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

Almacena un marcador de reinicio manual y solicita al code nativo que cree un WebView nuevo.

await WebViewCrash.restartWebView();
  • Android almacena los metadatos del crash de onRenderProcessGone, incluyendo didCrash y rendererPriorityAtExit cuando la plataforma los proporciona.
  • iOS almacena los metadatos de crash de webViewWebContentProcessDidTerminate y añade el estado actual de la app cuando esté disponible.
  • Los reinicios manuales y programados crean un WebView nuevo. Android recrea la activity host; iOS reconstruye la vista del bridge de Capacitor.
  • Los reinicios programados usan reason: 'periodicRestart'; los reinicios manuales usan reason: 'manualRestart'.
  • Web no detecta crashes reales del renderer. La implementación web solo simula el comportamiento con local storage.
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';

Esta página se genera a partir del plugin src/definitions.ts. Vuelve a ejecutar el sync cuando el API público cambie en upstream.

Si estás usando Primeros pasos para planificar el comportamiento de los medios nativos y la interfaz, conéctalo con Usando @capgo/capacitor-webview-crash para la capacidad nativa al usar @capgo/capacitor-webview-crash, Uso de @capgo/capacitor-live-activities para la capacidad nativa en Uso de @capgo/capacitor-live-activities, @capgo/capacitor-live-activities para los detalles de implementación en @capgo/capacitor-live-activities, Uso de @capgo/capacitor-video-player para la capacidad nativa en Uso de @capgo/capacitor-video-player, y @capgo/capacitor-video-player para el detalle de implementación en @capgo/capacitor-video-player.