본문 바로가기

시작하기

GitHub

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 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();

예시: simulateCrashRecovery

“예제: 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);
}

네이티브 자동 재시작

“네이티브 자동 재시작” 섹션

다음에 재시작 옵션을 설정하세요 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는 호스트 액티비티를 재생성하고, 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();

플랫폼 참고 사항

“Platform notes” 섹션
  • 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.tsupstream에서 public API가 변경되면 sync를 다시 실행하세요.

사용 중이라면 시작하기 네이티브 미디어 및 인터페이스 동작을 계획하려면, 이를 다음 항목과 연결하세요: @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.의 구현 세부 사항