Getting Started

설치

AI-Assisted Setup을 사용하여 플러그인을 설치할 수 있습니다. AI 도구에 Capgo 스킬을 추가하려면 다음 명령어를 사용하세요:

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

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

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

Import

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

권장 복구 흐름

앱 시작 시 가능한 한 빨리 리스너를 첨부하여 사용자가 계속 탐색하기 전에 복구된 런타임이 반응할 수 있도록 하세요:

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 자바스크립트 런타임이 충돌하거나 로드되지 않은 경우에도 native 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 사용 restartCron 사용 0 3 * * * 사용 reason: 'periodicRestart', then Android recreates the host activity and iOS rebuilds the Capacitor bridge view so a new WKWebView is created from native code.

사용 restartCron 사용 *사용 restartCron 는 설정되어 있습니다. restartIntervalMs 보다 큽니다. 0. 새로운 자바스크립트 런타임이 생성되기 때문에, 대기 중인 이벤트, 저장되지 않은 양식 상태, 현재 네비게이션 상태를 저장한 후 공격적인 스케줄을 사용하세요.

자체 네이티브 재시작

호출 restartWebView() 현재 자바스크립트 런타임이 네이티브 WebView를 대신할 필요가 있다고 결정했을 때, 예를 들어 메모리 집약적인 워크플로우 또는 장시간 비대면 세션에 들어가기 전에:

await WebViewCrash.restartWebView();

메서드는 pending marker를 생성하고 reason: 'manualRestart', 현재 호출을 해결한 후 네이티브 code에게 새로운 WebView를 생성하도록 요청합니다. Android는 호스트 활동을 다시 생성하고 iOS는 Capacitor 브릿지 뷰를 다시 빌드하여 새로운 WKWebView 생성되기 보다는 현재 페이지를 다시 로드하는 대신

API 개요

getPendingCrashInfo

저장된 네이티브 충돌 또는 재시작 마커를 반환하거나, 아무것도 대기 중이지 않으면. null 복사

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

clearPendingCrashInfo

복사

await WebViewCrash.clearPendingCrashInfo();

simulateCrashRecovery

복사

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

restartWebView

자동 재시작 마커를 저장하고 네이티브 code에게 새로운 WebView를 생성하도록 요청합니다.

await WebViewCrash.restartWebView();

플랫폼 참고

• Android는 onRenderProcessGone, 포함 didCrash 및 rendererPriorityAtExit 플랫폼이 제공할 때
• iOS는 webViewWebContentProcessDidTerminate 및 현재 애플리케이션 상태를 추가할 때 사용됩니다.
• 수동 및 예약된 재시작은 새로운 WebView를 생성합니다. Android는 호스트 활동을 재생성하고 iOS는 Capacitor 브리지 뷰를 다시 빌드합니다.
• 예약된 재시작은 reason: 'periodicRestart'; manual restarts use reason: 'manualRestart'.
• 웹은 실제 렌더러 충돌을 감지하지 못합니다. 웹 구현은 로컬 스토리지만을 사용하여 동작을 시뮬레이션합니다.

Type reference

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이 업스트림에서 변경될 때 다시 싱크를 실행하세요.

Getting Started에서 계속

Capgo를 사용 중이라면 Getting Started native 미디어 및 인터페이스 동작을 계획하고 연결하세요. Using @capgo/capacitor-webview-crash native 기능을 사용하는 Using @capgo/capacitor-webview-crash Using @capgo/capacitor-live-activities native 기능을 사용하는 Using @capgo/capacitor-live-activities @capgo/capacitor-live-activities native 구현 세부 정보는 @capgo/capacitor-live-activities Using @capgo/capacitor-video-player native 기능을 사용하는 Using @capgo/capacitor-video-player @capgo/capacitor-video-player native 구현 세부 정보는 @capgo/capacitor-video-player.