メインコンテンツへスキップ

スタートガイド

GitHub

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);
import { WebViewCrash } from '@capgo/capacitor-webview-crash';
await WebViewCrash.clearPendingCrashInfo();
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);
}

に再起動オプションを設定します 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 ユーザーが数日間同じ WebView を開き続ける常時稼働アプリ向けです。キオスク画面、コントロールルームのダッシュボード、倉庫のスキャナー、POS 端末、車載タブレット、デジタルサイネージなど。使用 restartCron 壁時計ベースの再起動(例:) 0 3 * * * デバイスのローカルタイムゾーンで毎日 03:00 に再起動します。スケジュール再起動は、 reason: 'periodicRestart'で保留マーカーを書き込み、その後 Android はホストアクティビティを再作成し、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が作成されるようにします。

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

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

復旧処理が完了した後に、保存されたマーカーをクリアします。

await WebViewCrash.clearPendingCrashInfo();

実際の WebView をクラッシュさせることなく、QA やローカルデバッグで復旧パスをテストできるように、偽のクラッシュマーカーを作成します。

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

手動再起動マーカーを保存し、ネイティブの code に新しい WebView の作成を要求します。

await WebViewCrash.restartWebView();

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

「プラットフォームの注意点」セクション
  • Android はクラッシュメタデータを以下から保存します onRenderProcessGone、以下を含む didCrash と rendererPriorityAtExit プラットフォームが提供する場合に。
  • iOS はクラッシュメタデータを webViewWebContentProcessDidTerminate から保存し、利用可能な場合は現在のアプリケーション状態を追加します。
  • 手動およびスケジュールされた再起動は、新しい WebView を作成します。Android はホストアクティビティを再作成し、iOS は Capacitor ブリッジビューを再構築します。
  • スケジュールされた再起動では次を使用します: reason: 'periodicRestart'、手動再起動では次を使用します: reason: 'manualRestart'.
  • Web は実際のレンダラークラッシュを検出できません。Web 実装はローカルストレージを使って動作をシミュレートするだけです。
export interface PendingCrashInfoResult {
/**
* Stored crash or restart metadata, or `null` when no marker is pending.
*/
value: WebViewCrashInfo | null;
}
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;
}
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;
}
export type WebViewCrashPlatform = 'android' | 'ios' | 'web';
export type WebViewCrashReason =
| 'renderProcessGone'
| 'webContentProcessDidTerminate'
| 'periodicRestart'
| 'manualRestart'
| 'simulated';
export type WebViewCrashAppState = 'active' | 'inactive' | 'background' | 'unknown';

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

Getting Startedの続きを進める

「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. の実装の詳細については