https://github.com/Cap-go/capacitor-webview-guardian
Capacitor plugin to Detect when the WebView was killed in the background and relaunch it on foreground.
https://github.com/Cap-go/capacitor-webview-guardian
capacitor capacitor-plugin
Last synced: 4 months ago
JSON representation
Capacitor plugin to Detect when the WebView was killed in the background and relaunch it on foreground.
- Host: GitHub
- URL: https://github.com/Cap-go/capacitor-webview-guardian
- Owner: Cap-go
- License: mpl-2.0
- Created: 2025-11-10T00:25:20.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-01-26T11:37:14.000Z (4 months ago)
- Last Synced: 2026-01-26T21:37:40.979Z (4 months ago)
- Topics: capacitor, capacitor-plugin
- Language: Swift
- Homepage: https://capgo.app
- Size: 565 KB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-ionic - capacitor-webview-guardian - Capacitor plugin to Detect when the WebView was killed in the background and relaunch it on foreground. (Capgo Capacitor Plugins)
- awesome-capacitor - WebView Guardian - Detect when the WebView was killed in the background and relaunch it on foreground. ([Capgo plugins](https://capgo.app/) / Utilities)
README
# @capgo/capacitor-webview-guardian
Keep your Capacitor app alive after the OS kills its WebView while the app is in the background. Webview Guardian listens for foreground events, probes the renderer, and reloads it automatically (or notifies you so you can recover your own state) when the render process was terminated.
## Compatibility
| Plugin version | Capacitor compatibility | Maintained |
| -------------- | ----------------------- | ---------- |
| v8.\*.\* | v8.\*.\* | ✅ |
| v7.\*.\* | v7.\*.\* | On demand |
| v6.\*.\* | v6.\*.\* | ❌ |
| v5.\*.\* | v5.\*.\* | ❌ |
> **Note:** The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.
## Install
```bash
npm install @capgo/capacitor-webview-guardian
npx cap sync
```
## Usage
```ts
import { WebviewGuardian } from '@capgo/capacitor-webview-guardian';
await WebviewGuardian.startMonitoring({
foregroundDebounceMs: 800,
autoRestart: true,
restartStrategy: 'reload',
});
WebviewGuardian.addListener('webviewRestarted', ({ reason }) => {
console.info('[guardian] WebView restarted', reason);
});
```
## API
* [`startMonitoring(...)`](#startmonitoring)
* [`stopMonitoring()`](#stopmonitoring)
* [`getState()`](#getstate)
* [`checkNow(...)`](#checknow)
* [`addListener('foreground' | 'webviewHealthy' | 'webviewCrashed' | 'webviewRestarted', ...)`](#addlistenerforeground--webviewhealthy--webviewcrashed--webviewrestarted-)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)
### startMonitoring(...)
```typescript
startMonitoring(options?: StartMonitoringOptions | undefined) => Promise
```
Starts observing foreground events and automatically checks the WebView health.
| Param | Type |
| ------------- | ------------------------------------------------------------------------- |
| **`options`** | StartMonitoringOptions |
**Returns:** Promise<GuardianState>
--------------------
### stopMonitoring()
```typescript
stopMonitoring() => Promise
```
Stops any automatic foreground monitoring.
**Returns:** Promise<GuardianState>
--------------------
### getState()
```typescript
getState() => Promise
```
Returns the latest known monitoring state.
**Returns:** Promise<GuardianState>
--------------------
### checkNow(...)
```typescript
checkNow(options?: CheckNowOptions | undefined) => Promise
```
Forces a WebView health probe immediately.
| Param | Type |
| ------------- | ----------------------------------------------------------- |
| **`options`** | CheckNowOptions |
**Returns:** Promise<CheckResult>
--------------------
### addListener('foreground' | 'webviewHealthy' | 'webviewCrashed' | 'webviewRestarted', ...)
```typescript
addListener(eventName: 'foreground' | 'webviewHealthy' | 'webviewCrashed' | 'webviewRestarted', listenerFunc: (event: GuardianEvent) => void) => Promise
```
| Param | Type |
| ------------------ | --------------------------------------------------------------------------------------- |
| **`eventName`** | 'foreground' \| 'webviewHealthy' \| 'webviewCrashed' \| 'webviewRestarted' |
| **`listenerFunc`** | (event: GuardianState) => void |
**Returns:** Promise<PluginListenerHandle>
--------------------
### Interfaces
#### GuardianState
| Prop | Type |
| -------------------------- | -------------------- |
| **`monitoring`** | boolean |
| **`reason`** | string |
| **`timestamp`** | string |
| **`lastHealthyAt`** | string |
| **`lastRestartAt`** | string |
| **`lastCrashAt`** | string |
| **`pendingRestartReason`** | string |
| **`error`** | string |
#### StartMonitoringOptions
| Prop | Type | Description |
| -------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`foregroundDebounceMs`** | number | Delay (in ms) before running a health check after the app re-enters the foreground. Defaults to 600ms to let the bridge finish resuming. |
| **`pingScript`** | string | Script executed via `evaluateJavascript`/`evaluateJavaScript` to confirm the WebView is alive. Defaults to `document.readyState`. |
| **`autoRestart`** | boolean | Automatically reloads the WebView when a terminated render process is detected. Disable to receive `webviewCrashed` events and restart manually. |
| **`restartStrategy`** | RestartStrategy | Strategy used when restarting the WebView. Defaults to `reload`. |
| **`customRestartUrl`** | string | Custom HTTPS/HTTP URL to load when `restartStrategy` is `customUrl`. |
| **`debug`** | boolean | Emits verbose logging in the native layer when true. |
| **`runInitialCheck`** | boolean | Whether an immediate health check should be executed right after enabling monitoring. Defaults to `true`. |
#### CheckResult
| Prop | Type |
| -------------------- | -------------------- |
| **`healthy`** | boolean |
| **`restarted`** | boolean |
| **`reason`** | string |
| **`timestamp`** | string |
| **`error`** | string |
| **`pendingRestart`** | boolean |
#### CheckNowOptions
| Prop | Type | Description |
| ------------ | ------------------- | ---------------------------------------------------------- |
| **`reason`** | string | Text tag describing why a manual check is being requested. |
#### PluginListenerHandle
| Prop | Type |
| ------------ | ----------------------------------------- |
| **`remove`** | () => Promise<void> |
### Type Aliases
#### RestartStrategy
'reload' | 'reloadFromOrigin' | 'customUrl'
#### GuardianEvent