본문 바로가기
@capgo/capacitor-webview-crash 인증 및 보안 오픈 소스

WebView 크래시 Capacitor 플러그인

크래시된 WebView를 네이티브로 재시작하고, 오래 실행된 WebView를 일정 간격으로 재활용합니다

설치

bun add @capgo/capacitor-webview-crash bunx cap sync
npm, pnpm 또는 yarn
  • npm install @capgo/capacitor-webview-crash
  • pnpm add @capgo/capacitor-webview-crash
  • yarn add @capgo/capacitor-webview-crash

가이드

Capacitor에서 WebView Crash 사용법

기기에서 테스트하기

Capgo 앱을 다운로드한 후 QR code을 스캔하세요.

WebView Crash 플러그인 미리보기 QR code

@capgo/capacitor-webview-crash 사용하기

복구된 WebView crash를 감지하고, 죽은 WebView를 네이티브로 재시작하며, 메모리 압박이 OOM으로 이어지기 전에 정해진 간격으로 장시간 실행된 WebView를 재활용합니다.

설치

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

플러그인이 제공하는 기능

  • iOS 및 Android에서 WebView crash 발생 시 네이티브 재시작 지원.
  • 며칠씩 실행되는 키오스크, POS, 사이니지, 스캐너, 대시보드 앱을 위한 일정 간격 네이티브 WebView 재시작.
  • restartWebView - 페이지를 새로고침하지 않고 JavaScript가 새 네이티브 WebView를 요청할 수 있습니다.
  • WebViewCrashPluginConfig - Types plugins.WebViewCrash 옵션에서 capacitor.config.ts.
  • getPendingCrashInfo - 저장된 네이티브 크래시 또는 재시작 마커를 반환하거나, null 대기 중인 항목이 없으면 null을 반환합니다.
  • clearPendingCrashInfo - 앱이 상태를 복원한 후 저장된 마커를 지웁니다.
  • simulateCrashRecovery - 로컬에서 복구 흐름을 테스트할 수 있도록 가짜 크래시 마커를 생성합니다.
  • webViewRestoredAfterCrash - 복구된 런타임에서 크래시 마커가 여전히 대기 중일 때 발화되는 리스너 이벤트.
  • webViewRestoredAfterRestart - 네이티브 재시작 마커가 여전히 대기 중일 때 발화되는 리스너 이벤트.

사용 예시

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

await WebViewCrash.addListener('webViewRestoredAfterCrash', async (info) => {
  console.log('Recovered after a WebView crash', info);
  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가 사용 불가능할 때도 계속 작동하도록 설정하세요:

import type { CapacitorConfig } from '@capacitor/cli';
import type { WebViewCrashPluginConfig } from '@capgo/capacitor-webview-crash';

const webViewCrash: WebViewCrashPluginConfig = {
  restartOnCrash: true,
  restartCron: '0 3 * * *',
  restartAfterCrashDelayMs: 0,
};

const config: CapacitorConfig = {
  plugins: {
    WebViewCrash: webViewCrash,
  },
};

export default config;

정기 재시작은 reason: 'periodicRestart'. 사용하세요 restartIntervalMs 고정 간격 또는 restartCron 디바이스 로컬 시간대의 5필드 cron 스케줄(예: 0 3 * * * 매일 03:00 재시작용입니다. 두 스케줄을 동시에 설정하지 마세요. 네이티브 초기화는 치명적인 구성 오류를 발생시킵니다. 다음 경우에 restartCron 이(가) 설정되어 있고 restartIntervalMs 값이 ...보다 크면 0)에 따라 동작합니다. 짧은 스케줄을 사용하기 전에 중요한 앱 상태를 저장하세요.

Native 수동 재시작

호출하세요 restartWebView() JavaScript가 네이티브 WebView를 선제적으로 교체해야 한다고 판단할 때, 예를 들어 메모리를 많이 쓰는 워크플로 이후:

await WebViewCrash.restartWebView();

이 메서드는 기록합니다 reason: 'manualRestart' 그리고 네이티브 code에 새 WebView 생성을 요청합니다. Android는 호스트 activity를 재생성하며, iOS는 Capacitor bridge view를 다시 빌드해 새 WKWebView WebView가 생성되도록 합니다. 현재 페이지를 다시 로드하는 대신입니다.

전체 레퍼런스

@capgo/capacitor-webview-crash 사용부터 계속하기

사용 중이라면 @capgo/capacitor-webview-crash 사용하기 네이티브 미디어 및 인터페이스 동작을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/capacitor-webview-crash @capgo/capacitor-webview-crash의 구현 세부 사항은 시작하기 Getting Started의 구현 상세 내용은 @capgo/capacitor-live-activities 사용 @capgo/capacitor-live-activities 사용에서의 네이티브 기능, @capgo/capacitor-live-activities @capgo/capacitor-live-activities의 구현 세부 사항은, 그리고 @capgo/capacitor-video-player 사용 @capgo/capacitor-video-player. 사용하기에서의 네이티브 기능은

자주 묻는 질문

WebView Crash 플러그인 FAQ

Capacitor 앱에 WebView Crash 플러그인을 어떻게 설치하나요?

"bun add @capgo/capacitor-webview-crash" (또는 "npm install @capgo/capacitor-webview-crash")를 실행한 다음, "bunx cap sync"를 실행해 iOS 및 Android 프로젝트에 native code가 반영되도록 하세요. 앱 code에서 "@capgo/capacitor-webview-crash"에서 import 하세요.

@capgo/capacitor-webview-crash가 React, Vue, Angular와 호환되나요?

네. WebView Crash는 Capacitor 패키지이므로 Ionic, React, Vue, Angular, Svelte 및 일반 JavaScript를 포함해 Capacitor 내에서 실행되는 모든 웹 프레임워크와 호환됩니다.

@capgo/capacitor-webview-crash는 어떤 Capacitor 버전을 지원하나요?

Capgo 플러그인은 Capacitor의 메이저 버전을 따릅니다. 사용 중인 Capacitor 메이저 버전과 일치하는 플러그인 메이저 버전을 사용하세요 (예: Capacitor 8에는 플러그인 v8). 유지 관리되는 버전은 GitHub README의 호환성 표에서 확인할 수 있습니다.

@capgo/capacitor-webview-crash는 무료 오픈 소스인가요?

네. 소스 코드(code)는 GitHub의 https://github.com/Cap-go/capacitor-webview-crash/에서 공개되어 있으며, 패키지는 npm에서 무료로 설치할 수 있습니다. 버그 리포트와 pull request는 언제나 환영합니다.

App Store 심사 없이 WebView Crash를 사용하는 code을 업데이트할 수 있나요?

플러그인을 설치하거나 업그레이드하면 네이티브 code가 변경되므로 새로운 스토어 빌드가 필요합니다. 그 이후에는 플러그인을 호출하는 JavaScript, HTML, CSS 변경 사항을 Capgo live updates로 즉시 배포할 수 있습니다.

앱 심사 대기 없이 WebView Crash 변경 사항을 배포하세요

스토어 빌드에 플러그인이 포함되면, Capgo live updates로 JavaScript, HTML, CSS 변경 사항을 몇 분 만에 사용자에게 푸시할 수 있습니다.

Capgo로 시작하기