Primeros pasos

Instalar

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:

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 los siguientes comandos y sigue las instrucciones específicas para cada plataforma a continuación:

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

Importar

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

Inicio rápido

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

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

Ejemplo: clearPendingCrashInfo

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

await WebViewCrash.clearPendingCrashInfo();

Ejemplo: simulateCrashRecovery

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

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

Errores comunes

• Listeners: eliminar los handles al desmontar las pantallas.
• Sync nativo: ejecutar bunx cap sync tras actualizar los plugins.
• Fuente de verdad: confiar src/definitions.ts en el repo de GitHub.

Flujo de recuperación recomendado

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

Reinicio nativo automático

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 la misma WebView abierta por días: pantallas de quiosco, dashboards de salas de control, scanners de almacén, terminales POS, tablets de flotas y señalización digital. Usa restartCron para reinicios en 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 desde el code nativo.

Elige un intervalo o un cron schedule que tu producto pueda tolerar. restartCron soporta *, listas, rangos y pasos. No configures ambos schedules a la vez: la inicialización nativa lanza un error de configuración fatal cuando restartCron está configurado y restartIntervalMs es mayor que 0. Un reinicio crea un runtime de JavaScript limpio, así que persiste los eventos en cola, el estado de formularios sin guardar y el estado de navegación actual antes de usar schedules agresivos.

Reinicio nativo manual

Llama 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 de 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.

Resumen de API

getPendingCrashInfo

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

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

clearPendingCrashInfo

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

await WebViewCrash.clearPendingCrashInfo();

simulateCrashRecovery

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

restartWebView

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

await WebViewCrash.restartWebView();

Notas de la plataforma

• 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 si está disponible.
• Los reinicios manuales y programados crean un WebView nuevo. Android recrea la activity host; iOS reconstruye la vista del bridge 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.

Referencia de tipos

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

Fuente de verdad

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

Continúa desde Primeros pasos

Si estás usando Primeros pasos para planificar el comportamiento de los medios y la interfaz nativos, conéctalo con Uso de @capgo/capacitor-webview-crash para la capacidad nativa en Uso de @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 el detalle de implementación en @capgo/capacitor-live-activities, Uso de @capgo/capacitor-video-player para la capacidad nativa en Using @capgo/capacitor-video-player, y @capgo/capacitor-video-player para los detalles de implementación en @capgo/capacitor-video-player.