Capacitor plugin for checking whether the app WebView engine is up to date, emitting realtime status events, and optionally showing a native update prompt that redirects users to the proper update destination.

bun add @capgo/capacitor-webview-version-checker
bunx cap sync

Main use case: Browserslist-style compatibility checks by default.

The plugin uses this strategy out of the box, even if you do not add any plugin options:

• minimumDeviceSharePercent defaults to 3
• version-share data comes from a built-in dataset generated at build time from caniuse
• no runtime version-share URL call is required for the default flow

Default setup (no plugin settings):

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    WebviewVersionChecker: {},
  },
};

export default config;

Simple config-only setup with native prompt:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    WebviewVersionChecker: {
      autoPromptOnOutdated: true,
      autoPromptDismissible: false,
    },
  },
};

export default config;

Advanced mode with custom threshold and custom dataset:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    WebviewVersionChecker: {
      autoCheckOnLoad: true,
      autoPromptOnOutdated: true,
      minimumDeviceSharePercent: 3,
      versionShareByMajor: {
        '137': 58.2,
        '136': 21.3,
        '135': 4.6,
        '134': 2.1,
      },
    },
  },
};

export default config;

What this means:

• minimumDeviceSharePercent: 3 means "consider a version compatible only if that major version still represents at least 3% of devices in my dataset".
• versionShareByMajor is your own dataset map where:
  • key = major version (for example 137)
  • value = share percent (0..100)
• If you do not provide versionShareByMajor, the plugin uses its built-in generated dataset.

You can provide share data in two ways:

• Inline with versionShareByMajor (as shown above)
• Remote with versionShareApiUrl returning one of these shapes:
  • { "versionShareByMajor": { "137": 54.2, "136": 23.8 } }
  • { "shareByMajor": { "137": 54.2, "136": 23.8 } }
  • { "versions": [{ "major": 137, "share": 54.2 }, { "version": "136.0.0.0", "percent": 23.8 }] }

If you set versionShareApiUrl, the plugin fetches that URL at runtime and uses it as override.

Evaluation order:

1. Browserslist-style threshold mode (minimumDeviceSharePercent + share dataset) is used first. By default this is 3% with the built-in generated dataset.
2. Else the plugin compares against latestVersion / latestVersionApiUrl.
3. Else it falls back to minimumMajorVersion.

Advanced usage with JavaScript (manual check, listeners, custom prompt):

import { WebviewVersionChecker } from '@capgo/capacitor-webview-version-checker';

const listener = await WebviewVersionChecker.addListener('webViewOutdated', (status) => {
  console.log('Outdated WebView detected', status);
});

const status = await WebviewVersionChecker.check({
  latestVersionApiUrl:
    'https://versionhistory.googleapis.com/v1/chrome/platforms/android/channels/stable/versions?page_size=1',
  minimumMajorVersion: 124,
  showPromptOnOutdated: true,
  autoPromptDismissible: false,
  promptTitle: 'Update WebView',
  promptMessage: 'Your WebView is outdated. Please update to continue safely.',
  promptUpdateButtonText: 'Update now',
  promptCancelButtonText: 'Later',
});

console.log('WebView status', status);

// later
listener.remove();

Capacitor already provides a built-in WebView minimum check through config:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  android: {
    minWebViewVersion: 124,
  },
  server: {
    errorPath: 'unsupported-webview.html',
  },
};

export default config;

• android.minWebViewVersion is static config; it does not give runtime plugin events like webViewOutdated.
• With server.errorPath, users are redirected to a static error page (hard block UX) instead of seeing a native modal in your normal app flow.
• Without server.errorPath, Capacitor only logs the issue, but does not provide a native update prompt + store deep link UX.
• This plugin gives soft enforcement: users can still open/use the app, get a native update modal, and you decide whether to require update later.
• Main use case: this plugin brings Browserslist-style compatibility logic to Android WebView (for example, "support versions still used by at least 3% of devices"), while keeping your app usable.

The plugin resolves the active WebView provider package and version, then routes update links to the correct package:

• Android 5-6 and 10+: Android System WebView (com.google.android.webview)
• Android 7-9: Google Chrome (com.android.chrome)

When provider detection is unavailable, fallback routing follows the same API-range rule above.

• check(...)
• startMonitoring(...)
• stopMonitoring()
• getLastStatus()
• showUpdatePrompt(...)
• openUpdatePage(...)
• addListener('statusChanged', ...)
• addListener('webViewLatest', ...)
• addListener('webViewOutdated', ...)
• Interfaces
• Type Aliases

Public API for checking WebView freshness and guiding users to updates.

check(options?: CheckWebViewOptions | undefined) => Promise<WebViewVersionStatus>

Runs a version check and returns the latest known status.

Returns: Promise<WebViewVersionStatus>

startMonitoring(options?: StartMonitoringOptions | undefined) => Promise<MonitoringStateResult>

Enables background monitoring (typically on app resume).

Returns: Promise<MonitoringStateResult>

stopMonitoring() => Promise<MonitoringStateResult>

Disables monitoring.

Returns: Promise<MonitoringStateResult>

getLastStatus() => Promise<LastStatusResult>

Returns the last resolved status, or null if no check was run yet.

Returns: Promise<LastStatusResult>

showUpdatePrompt(options?: ShowUpdatePromptOptions | undefined) => Promise<ShowUpdatePromptResult>

Shows a native prompt asking the user to update the WebView.

Returns: Promise<ShowUpdatePromptResult>

openUpdatePage(options?: OpenUpdatePageOptions | undefined) => Promise<OpenUpdatePageResult>

Opens the configured update page directly.

Returns: Promise<OpenUpdatePageResult>

addListener(eventName: 'statusChanged', listenerFunc: (status: WebViewVersionStatus) => void) => Promise<PluginListenerHandle>

Fired for every successful status evaluation.

Returns: Promise<PluginListenerHandle>

addListener(eventName: 'webViewLatest', listenerFunc: (status: WebViewVersionStatus) => void) => Promise<PluginListenerHandle>

Fired when the state resolves to latest.

Returns: Promise<PluginListenerHandle>

addListener(eventName: 'webViewOutdated', listenerFunc: (status: WebViewVersionStatus) => void) => Promise<PluginListenerHandle>

Fired when the state resolves to outdated.

Returns: Promise<PluginListenerHandle>

Snapshot of the currently detected WebView status.

Options for running a WebView version check.

Result payload for monitor controls.

Options for starting monitor mode.

Last known check snapshot.

Result payload for showUpdatePrompt().

Options for showing the native update prompt.

Result payload for openUpdatePage().

Options for opening the update page directly.

'android' | 'ios' | 'web'

'latest' | 'outdated' | 'unknown'