Démarrage

Installer

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

Définir 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 chargé encore :

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;

Utiliser restartIntervalMs pour les applications toujours allumées où les utilisateurs peuvent conserver la même Vue Web ouverte pendant des jours : écrans de kiosque, tableaux de bord de salle de contrôle, scanners de entrepôt, terminaux de caisse, tablettes de flotte et affichages numériques. Utiliser restartCron pour les redémarrages horloges telles que 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 mise en attente avec reason: 'periodicRestart', puis Android recrée l'activité de l'hôte et iOS reçoit à nouveau la vue de pont Capacitor pour créer un nouveau WKWebView est créé à partir de code natif.

Choisissez une plage ou un calendrier de planification que votre produit peut supporter. restartCron supporte *, listes, plages et étapes. N'configurez pas les deux plans de mise en œuvre à la fois : l'initialisation native lance une erreur de configuration mortelle lorsque restartCron est défini et restartIntervalMs est supérieur à 0. Un redémarrage crée un runtime JavaScript frais, donc persistez les événements en attente, l'état non enregistré des formulaires et l'état de navigation actuel avant d'utiliser des plans d'agression.

Redémarrage natif manuel

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

await WebViewCrash.restartWebView();

La méthode écrit un marqueur de crash ou de redémarrage en attente avec __CAPGO_KEEP_0__, résout l'appel actuel, puis demande au __CAPGO_KEEP_0__ natif de créer une vue Webview fraîche. Android recrée l'activité hôte. iOS reçoit le pont de vue __CAPGO_KEEP_1__ et crée une nouvelle reason: 'manualRestart', resolves the current call, then asks native code to create a fresh WebView. Android recreates the host activity. iOS rebuilds the Capacitor bridge view so a new WKWebView __CAPGO_KEEP_0__ : Présentation

Section intitulée “API : Présentation”

getPendingCrashInfo

lorsque rien n'est en attente. null Copier dans le presse-papier

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

clearPendingCrashInfo

Supprime le marqueur stocké après la gestion de votre récupération est terminée.

await WebViewCrash.clearPendingCrashInfo();

simulateCrashRecovery

Crée un marqueur de crash fictif afin que les équipes QA et les débogages locaux puissent exercer la voie 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 à code natif de créer une WebView fraîche.

await WebViewCrash.restartWebView();

Notes de plateforme

• Android stocke les métadonnées de crash à partir de onRenderProcessGone , y compris didCrash et quand la plateforme les fournit. rendererPriorityAtExit iOS enregistre les métadonnées de crash des magasins.
• et ajoute l'état de l'application actuelle lorsqu'il est disponible. webViewWebContentProcessDidTerminate Les redémarrages manuels et planifiés créent une vue WebView fraîche. Android reçoit à nouveau l'activité hôte ; iOS reçoit à nouveau la vue de pont __CAPGO_KEEP_0__.
• Manual and scheduled restarts create a fresh WebView. Android recreates the host activity; iOS rebuilds the Capacitor bridge view.
• ; les redémarrages manuels utilisent reason: 'periodicRestart'La mise en œuvre web ne détecte pas les crashs de rendu réels. La mise en œuvre web ne simule que le comportement avec le stockage local. reason: 'manualRestart'.
• Référence de type

Section intitulée “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é

This page is generated from the plugin’s src/definitions.tsRe-run the synchronisation when the public API changes upstream.

Continuez de l'étape « Débuter »

Si vous utilisez Débuter pour planifier le comportement des médias et de l'interface native, connectez-le avec Utiliser @capgo/capacitor-webview-crash pour la capacité native dans Utiliser @capgo/capacitor-webview-crash, Utiliser @capgo/capacitor-live-activities pour la capacité native dans Utiliser @capgo/capacitor-live-activities, @capgo/capacitor-live-activities pour les détails d'implémentation dans @capgo/capacitor-activités-en-vive En utilisant @capgo/capacitor-joueur-de-videos pour la capacité native dans En utilisant @capgo/capacitor-joueur-de-videos, et @capgo/capacitor-joueur-de-videos pour les détails d'implémentation dans @capgo/capacitor-joueur-de-videos.