Getting Started

Installez

Vous pouvez utiliser notre configuration assistée par l'IA pour installer le plugin. Ajoutez les Capgo compétences à votre outil IA à l'aide de la commande suivante :

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Utilisez ensuite la commande suivante :

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

Si vous préférez la configuration manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à la plateforme ci-dessous :

npm install @capgo/capacitor-webview-crash
npx cap sync

Importer

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

Flux de récupération recommandé

Attachez les écouteurs aussi tôt que possible dans le démarrage de votre application afin que le runtime récupéré puisse réagir avant que les utilisateurs continuent à naviguer.

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

Redémarrage auto natif

Configurez les options de redémarrage dans capacitor.config.ts afin que la décision reste dans le code natif même lorsque le runtime JavaScript a crashé ou n'a pas encore chargé :

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;

Utilisez restartIntervalMs for always-on apps where users may keep the same WebView open for days: kiosk screens, control-room dashboards, warehouse scanners, POS terminals, fleet tablets, and digital signage. Use restartCron pour les redémarrages horloges, comme 0 3 * * * pour un redémarrage quotidien à 03 :00 dans la zone horaire locale du dispositif. Les redémarrages planifiés écrivent un marqueur de retard avec reason: 'periodicRestart'puis Android recrée l'activité hôte et iOS reconstitue la vue de pont Capacitor afin qu'un nouveau WKWebView est créé à partir de native code.

Choisissez une plage ou un horaire planifié que votre produit peut supporter. restartCron supporte *, listes, plages et étapes. N'configurez pas les deux plans à la fois : l'initialisation native provoque une erreur de configuration mortelle lorsque restartCron est défini et restartIntervalMs est supérieur à 0Avant de lancer un emploi du temps agressif, persistez les événements en attente, les données de formulaire non enregistrées et l'état de navigation actuel.

Redémarrage natif manuel

Appelez restartWebView() Lorsque le runtime JavaScript actuel décide que le WebView natif doit être remplacé de manière proactive, par exemple après un flux de travail lourd en mémoire ou avant d'entrer dans une longue session non surveillée :

await WebViewCrash.restartWebView();

La méthode écrit un marqueur en attente avec reason: 'manualRestart', résout l'appel actuel, puis demande au code natif de créer une nouvelle vue WebView. Android reçoit une nouvelle activité hôte. iOS reçoit une nouvelle vue de pont Capacitor pour créer une nouvelle WKWebView au lieu de recharger la page actuelle.

API : vue d'ensemble

getPendingCrashInfo

Retourne le marqueur de panne ou de redémarrage natif stocké, ou null lorsqu'il n'y a rien en attente.

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

clearPendingCrashInfo

Efface le marqueur stocké après que vos traitements de récupération soient terminés.

await WebViewCrash.clearPendingCrashInfo();

simulateCrashRecovery

Crée un marqueur de crash fictif afin que les équipes QA et de débogage local puissent exercer le chemin de récupération sans faire crasher une vraie WebView.

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

restartWebView

Stocke un marqueur de redémarrage manuel et demande au code natif de créer une WebView fraîche.

await WebViewCrash.restartWebView();

Remarques de plateforme

• Android stocke les métadonnées de crash depuis onRenderProcessGoney compris didCrash et rendererPriorityAtExit Lorsque la plateforme les fournit.
• iOS stocke les métadonnées des crash provenant de webViewWebContentProcessDidTerminate et ajoute l'état de l'application actuelle lorsqu'il est disponible.
• Les redémarrages manuels et programmés créent une nouvelle vue WebView. L'Android reçoit à nouveau l'activité hôte ; l'iOS reçoit à nouveau la vue de pont Capacitor.
• Les redémarrages programmés utilisent reason: 'periodicRestart'Les redémarrages manuels utilisent reason: 'manualRestart'.
• La mise en œuvre web ne détecte pas les crashs de rendu réels. L'implémentation web ne simule que le comportement avec le stockage local.

Référence de type

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

Source De Vérité

Cette page est générée à partir du plugin’s src/definitions.tsRe-run la synchronisation lorsque la publication API change en amont.

Continuez de là depuis Getting Started

Si vous utilisez Getting Started pour planifier le comportement de médias et d'interface natifs, connectez-l’à Utilisez @capgo/capacitor-webview-crash pour la capacité native dans Utilisez @capgo/capacitor-webview-crash Utilisez @capgo/capacitor-live-activities pour la capacité native dans Utilisez @capgo/capacitor-live-activities @capgo/capacitor-activités en direct pour le détail d'implémentation dans @capgo/capacitor-live-activities Utilisez @capgo/capacitor-video-player pour la capacité native dans L'utilisation de @capgo/capacitor-video-player, et @capgo/capacitor-joueur-de-videos pour le détail d'implémentation dans @capgo/capacitor-video-player.