はじめに

インストール

AIアシストセットアップを使ってプラグインをインストールできます。以下のコマンドで、お使いのAIツールに Capgo スキルを追加してください：

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

次に、以下のプロンプトを使用します：

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

手動セットアップを希望する場合は、以下のコマンドでプラグインをインストールし、下記のプラットフォーム別の手順に従ってください：

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

例: clearPendingCrashInfo

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

await WebViewCrash.clearPendingCrashInfo();

例: simulateCrashRecovery

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

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

よくある落とし穴

• リスナー: 画面のアンマウント時にハンドルを削除してください。
• ネイティブ同期: 実行 bunx cap sync プラグインのアップグレード後。
• 信頼できる情報源: 信頼する src/definitions.ts GitHub リポジトリ内に

推奨されるリカバリフロー

ユーザーが操作を続ける前に、リカバリ後のランタイムが反応できるように、アプリの起動プロセス中のできるだけ早い段階でリスナーをアタッチしてください：

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

Native auto restart

restart options を以下に設定します： capacitor.config.ts これにより、JavaScriptランタイムがクラッシュしている場合や、まだロードされていない場合でも、code のネイティブ側で決定を維持できます：

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;

使用するのは 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 次のような、決まった時刻での再起動には： 0 3 * * * デバイスのローカルタイムゾーンで毎日03:00に再起動を実行します。スケジュールされた再起動では、以下の内容を含む保留中のマーカーが書き込まれます。 reason: 'periodicRestart'その後、AndroidはホストActivityを再生成し、iOSは Capacitor ブリッジビューを再構築するため、新しい WKWebView がネイティブの code から作成されます。

プロダクトが許容できる間隔、またはcronスケジュールを選択してください。 restartCron は以下をサポートしています： *、リスト、範囲、およびステップです。両方のスケジュールを同時に設定しないでください。設定が重複していると、ネイティブの初期化時に致命的な設定エラーが発生します。 restartCron が restartIntervalMs より大きい場合、 0ネイティブの初期化時に致命的な設定エラーが発生します。再起動によってJavaScriptランタイムが新しくなるため、頻繁なスケジュールを使用する場合は、キュー内のイベント、保存されていないフォームの状態、および現在のナビゲーション状態を事前に保存してください。

手動でのネイティブ再起動

呼び出す restartWebView() メモリを大量に消費するワークフローの後や、長時間放置されるセッションが始まる前など、現在のJavaScriptランタイムがネイティブWebViewの積極的なリプレイスが必要だと判断した場合：

await WebViewCrash.restartWebView();

このメソッドは、保留中のマーカーを reason: 'manualRestart'に書き込み、現在の呼び出しを解決した後、ネイティブの code に新しいWebViewの作成を依頼します。AndroidはホストActivityを再生成します。iOSは Capacitor ブリッジビューを再構築し、新しい WKWebView WebView が作成されます（現在のページをリロードするのではなく）。

API の概要

getPendingCrashInfo

保存されているネイティブのクラッシュまたは再起動マーカーを返します。または、 null 保留中のものがない場合です。

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

clearPendingCrashInfo

リカバリ処理の完了後、保存されているマーカーをクリアします。

await WebViewCrash.clearPendingCrashInfo();

simulateCrashRecovery

擬似的なクラッシュマーカーを作成します。これにより、実際のWebViewをクラッシュさせることなく、QAやローカルデバッグでリカバリパスの検証が可能になります。

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

restartWebView

手動再起動用のマーカーを保存し、ネイティブの code に新しいWebViewの作成をリクエストします。

await WebViewCrash.restartWebView();

プラットフォーム別の注意点

• Androidは以下の場所からクラッシュのメタデータを保存します onRenderProcessGone（以下を含む） didCrash と rendererPriorityAtExit プラットフォームから提供される場合。
• iOSは、以下からのクラッシュメタデータを保存します： webViewWebContentProcessDidTerminate また、利用可能な場合は現在のアプリケーションの状態も追加されます。
• 手動またはスケジュールされた再起動により、新しいWebViewが作成されます。AndroidではホストActivityが再生成され、iOSでは Capacitor bridge viewが再構築されます。
• スケジュールされた再起動には reason: 'periodicRestart'を使用し、手動の再起動には reason: 'manualRestart'.
• を使用します。Web環境では実際のレンダラーのクラッシュを検知できません。Webの実装では、ローカルストレージを使用してその挙動をシミュレートするのみです。

型リファレンス

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

信頼できる情報源

このページはプラグインの src/definitions.tsから生成されています。上流で公開 API が変更されたら、sync を再実行してください。

Getting Started から続ける

以下を使用している場合： はじめに ネイティブのメディアとインターフェースの挙動を計画するには、これを次と連携させてください： @capgo/capacitor-webview-crash の使用方法 @capgo/capacitor-webview-crash を使用してネイティブ機能を利用する場合、 @capgo/capacitor-live-activities の使用 @capgo/capacitor-live-activities を使用したネイティブ機能について、 @capgo/capacitor-live-activities @capgo/capacitor-live-activities の実装詳細について、 @capgo/capacitor-video-player の使用 @capgo/capacitor-video-player を使用したネイティブ機能、および @capgo/capacitor-video-player @capgo/capacitor-video-player. の実装詳細