Per iniziare

Installa

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

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

Importa

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

Avvio rapido

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

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

Esempio: clearPendingCrashInfo

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

await WebViewCrash.clearPendingCrashInfo();

Esempio: simulateCrashRecovery

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

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

Errori comuni

• 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.

Flusso di recovery consigliato

Registra i listener il prima possibile all'avvio dell'app, così il runtime recuperato può reagire prima che l'utente continui la navigazione:

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

Configura le opzioni di restart in capacitor.config.ts così la decisione rimane nel code nativo anche se il runtime JavaScript è crashato o non è ancora stato 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 app sempre attive dove gli utenti tengono la stessa WebView aperta per giorni: kiosk, dashboard di sale controllo, scanner di magazzino, terminali POS, tablet aziendali e digital signage. Usa restartCron per riavvii a orario prestabilito come 0 3 * * * per un riavvio giornaliero alle 03:00 nel fuso orario locale del dispositivo. I riavvii pianificati scrivono un marker di attesa con reason: 'periodicRestart', quindi Android ricrea l'activity host e iOS ricostruisce la vista bridge di Capacitor così viene creata una nuova WKWebView partendo dal code nativo.

Scegli un intervallo o un cron schedule che il tuo prodotto può tollerare. restartCron supporta *, liste, intervalli e step. Non configurare entrambi gli schedule contemporaneamente: l'inizializzazione nativa genera un errore di config fatale quando restartCron è impostato e restartIntervalMs è maggiore di 0. Un riavvio crea un nuovo runtime JavaScript, quindi salva gli eventi in coda, lo stato dei form non salvati e lo stato di navigazione corrente prima di usare schedule aggressivi.

Riavvio nativo manuale

Chiama restartWebView() quando il runtime JavaScript corrente decide che la WebView nativa debba essere sostituita proattivamente, ad esempio dopo un workflow ad alto consumo di memoria o prima di una sessione prolungata senza supervisione:

await WebViewCrash.restartWebView();

Il metodo scrive un marker di attesa con reason: 'manualRestart', risolve la chiamata corrente, quindi chiede alla code nativa di creare una nuova WebView. Android ricrea l'activity host. iOS ricostruisce la Capacitor bridge view in modo che venga creata una nuova WKWebView invece di ricaricare la pagina corrente.

Panoramica di API

getPendingCrashInfo

Restituisce il crash nativo o il marker di riavvio salvato, oppure null quando non ci sono operazioni in sospeso.

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

clearPendingCrashInfo

Cancella il marker salvato una volta terminata la gestione del recovery.

await WebViewCrash.clearPendingCrashInfo();

simulateCrashRecovery

Crea un finto marker di crash per permettere a QA e al debugging locale di testare il percorso di recovery senza crashare una WebView reale.

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

restartWebView

Salva un marker di restart manuale e chiede al code nativo di creare una nuova WebView.

await WebViewCrash.restartWebView();

Note sulla piattaforma

• Android salva i metadati del crash da onRenderProcessGone, inclusi didCrash e rendererPriorityAtExit quando forniti dalla piattaforma.
• iOS memorizza i metadati del crash di webViewWebContentProcessDidTerminate e aggiunge lo stato attuale dell'app, se disponibile.
• I riavvii manuali e pianificati creano una nuova WebView. Android ricrea l'activity host; iOS ricostruisce la vista bridge di Capacitor.
• I riavvii pianificati utilizzano reason: 'periodicRestart'; i riavvii manuali utilizzano reason: 'manualRestart'.
• Il Web non rileva i crash reali del renderer. L'implementazione web simula solo il comportamento tramite local storage.

Riferimento tipi

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

Fonte di verità

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

Continua da Getting Started

Se stai usando Per iniziare per pianificare il comportamento dei media nativi e dell'interfaccia, collegalo a Utilizzo di @capgo/capacitor-webview-crash per la funzionalità nativa in Utilizzo di @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.