시작하기

설치

AI 지원 설정으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

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

그다음 아래 prompt를 사용하세요:

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

Manual Setup을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

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

자주 하는 실수

• 리스너: 화면이 unmount될 때 핸들을 제거하세요.
• 네이티브 동기화: 실행 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 자동 재시작

다음에서 재시작 옵션을 설정하세요: capacitor.config.ts 이렇게 하면 JavaScript 런타임이 충돌하거나 아직 로드되지 않은 상태에서도 결정권이 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 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 bridge view를 다시 빌드하여 새로운 WKWebView 이(가) 네이티브 code로부터 생성됩니다.

서비스가 허용 가능한 간격 또는 cron 스케줄을 선택하세요. restartCron 은(는) 다음을 지원합니다: *, 리스트, 범위 및 단계입니다. 두 스케줄을 동시에 설정하지 마세요. 설정 시 native initialization 과정에서 치명적인 config 에러가 발생합니다. restartCron 이(가) 설정된 상태에서 restartIntervalMs 이(가) 0보다 크면 네이티브 초기화 시 치명적인 설정 오류가 발생합니다. 재시작 시 새로운 JavaScript runtime이 생성되므로, 공격적인 스케줄을 사용하기 전에 대기 중인 이벤트, 저장되지 않은 폼 상태, 현재 네비게이션 상태를 반드시 유지(persist)하세요.

Native 수동 재시작

실행하세요: restartWebView() 메모리 사용량이 많은 워크플로우를 마친 후나, 장시간 방치되는 세션에 진입하기 전과 같이 현재 JavaScript 런타임이 네이티브 WebView를 선제적으로 교체해야 한다고 판단할 때 다음과 같이 동작합니다:

await WebViewCrash.restartWebView();

이 메서드는 다음 정보를 포함한 대기 마커를 기록하고 reason: 'manualRestart', 현재 호출을 완료한 뒤, 네이티브 code에 새로운 WebView 생성을 요청합니다. Android는 호스트 Activity를 재생성하며, iOS는 Capacitor bridge view를 다시 빌드하여 새로운 WKWebView WebView가 현재 페이지를 다시 로드하는 대신 생성됩니다.

API 개요

getPendingCrashInfo

저장된 네이티브 crash 또는 재시작 마커를 반환하거나, 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에서 생성되었습니다. public API가 업스트림에서 변경되면 동기화를 다시 실행하세요.

Getting Started에서 계속하기

사용 중인 경우 시작하기 네이티브 미디어 및 인터페이스 동작을 설계하려면, 이를 다음 항목과 연결하세요 @capgo/capacitor-webview-crash 사용하기 @capgo/capacitor-webview-crash를 사용하여 Native Build 기능을 구현하려면, @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.의 구현 세부 사항에 대해서는