@capgo/capacitor-webview-version-checker 8.0.0 → 8.2.0

package/README.md

@@ -6,7 +6,7 @@
   <h2><a href="https://capgo.app/consulting/?ref=plugin_webview_version_checker"> Missing a feature? We’ll build the plugin for you 💪</a></h2>
 </div>
 
-Capacitor plugin to detect whether the app WebView engine is up to date, emit realtime status events, and optionally show a native update prompt that redirects users to the proper update destination.
+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.
 
 ## Install
 
@@ -17,7 +17,45 @@ bunx cap sync
 
 ## Usage
 
-Simple setup (config only):
+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):
+
+```ts
+import type { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  plugins: {
+    WebviewVersionChecker: {},
+  },
+};
+
+export default config;
+```
+
+Simple config-only setup with native prompt:
+
+```ts
+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:
 
 ```ts
 import type { CapacitorConfig } from '@capacitor/cli';
@@ -26,8 +64,14 @@ const config: CapacitorConfig = {
   plugins: {
     WebviewVersionChecker: {
       autoCheckOnLoad: true,
-      autoCheckOnResume: true,
       autoPromptOnOutdated: true,
+      minimumDeviceSharePercent: 3,
+      versionShareByMajor: {
+        '137': 58.2,
+        '136': 21.3,
+        '135': 4.6,
+        '134': 2.1,
+      },
     },
   },
 };
@@ -35,6 +79,27 @@ const config: CapacitorConfig = {
 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):
 
 ```ts
@@ -49,6 +114,7 @@ const status = await WebviewVersionChecker.check({
     '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',
@@ -86,6 +152,7 @@ export default config;
 - 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.
 
 ## Android Provider Handling
 
@@ -273,20 +340,24 @@ Fired when the state resolves to `outdated`.
 
 Snapshot of the currently detected WebView status.
 
-| Prop                      | Type                                                                | Description                                              |
-| ------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------- |
-| **`platform`**            | <code><a href="#webviewplatform">WebViewPlatform</a></code>         | Native platform that generated the status.               |
-| **`state`**               | <code><a href="#webviewversionstate">WebViewVersionState</a></code> | Resolved version state.                                  |
-| **`isLatest`**            | <code>boolean</code>                                                | Convenience boolean equivalent to `state === 'latest'`.  |
-| **`checkedAt`**           | <code>string</code>                                                 | ISO-8601 timestamp of the check.                         |
-| **`reason`**              | <code>string</code>                                                 | Human-readable explanation for the reported state.       |
-| **`currentVersion`**      | <code>string</code>                                                 | Current WebView (or iOS system WebKit) version string.   |
-| **`currentMajorVersion`** | <code>number</code>                                                 | Current detected major version (if parseable).           |
-| **`latestVersion`**       | <code>string</code>                                                 | Resolved latest version used for comparison.             |
-| **`latestMajorVersion`**  | <code>number</code>                                                 | Resolved latest major version (if parseable).            |
-| **`providerPackage`**     | <code>string</code>                                                 | Android package name of the active WebView provider.     |
-| **`updateUrl`**           | <code>string</code>                                                 | URL that should be opened to update when outdated.       |
-| **`source`**              | <code>string</code>                                                 | Internal source identifier for the check implementation. |
+| Prop                             | Type                                                                | Description                                                                                                                                                                                              |
+| -------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`platform`**                   | <code><a href="#webviewplatform">WebViewPlatform</a></code>         | Native platform that generated the status.                                                                                                                                                               |
+| **`state`**                      | <code><a href="#webviewversionstate">WebViewVersionState</a></code> | Resolved version state.                                                                                                                                                                                  |
+| **`isLatest`**                   | <code>boolean</code>                                                | Convenience boolean equivalent to `state === 'latest'`.                                                                                                                                                  |
+| **`checkedAt`**                  | <code>string</code>                                                 | ISO-8601 timestamp of the check.                                                                                                                                                                         |
+| **`reason`**                     | <code>string</code>                                                 | Human-readable explanation for the reported state.                                                                                                                                                       |
+| **`currentVersion`**             | <code>string</code>                                                 | Current WebView (or iOS system WebKit) version string.                                                                                                                                                   |
+| **`currentMajorVersion`**        | <code>number</code>                                                 | Current detected major version (if parseable).                                                                                                                                                           |
+| **`latestVersion`**              | <code>string</code>                                                 | Resolved latest version used for comparison.                                                                                                                                                             |
+| **`latestMajorVersion`**         | <code>number</code>                                                 | Resolved latest major version (if parseable).                                                                                                                                                            |
+| **`currentVersionSharePercent`** | <code>number</code>                                                 | Device-share percentage for the installed WebView major version. Present only when a version-share dataset is available and includes the current major version.                                          |
+| **`minimumDeviceSharePercent`**  | <code>number</code>                                                 | Configured threshold used by compatibility-threshold mode. Present only when `minimumDeviceSharePercent` was requested for that check.                                                                   |
+| **`versionShareSource`**         | <code>string</code>                                                 | Source used for version-share data. Values: - `versionShareByMajor` (inline dataset) - `versionShareApiUrl` (remote dataset) - `generatedVersionShareByMajor` (built-in dataset generated at build time) |
+| **`deviceShareError`**           | <code>string</code>                                                 | Diagnostic message for compatibility-threshold mode. Present when `minimumDeviceSharePercent` was requested but the threshold check could not be fully evaluated.                                        |
+| **`providerPackage`**            | <code>string</code>                                                 | Android package name of the active WebView provider.                                                                                                                                                     |
+| **`updateUrl`**                  | <code>string</code>                                                 | URL that should be opened to update when outdated.                                                                                                                                                       |
+| **`source`**                     | <code>string</code>                                                 | Internal source identifier for the check implementation.                                                                                                                                                 |
 
 
 #### CheckWebViewOptions

package/android/build.gradle

@@ -31,7 +31,7 @@ android {
     buildTypes {
         release {
             minifyEnabled false
-            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
         }
     }
     lintOptions {

package/android/src/main/java/app/capgo/webviewversionchecker/GeneratedVersionShareData.java

@@ -0,0 +1,28 @@
+package app.capgo.webviewversionchecker;
+
+import org.json.JSONObject;
+
+final class GeneratedVersionShareData {
+
+    private static final String GENERATED_AT = "2026-02-22T16:25:02.516Z";
+    private static final String DATA_SOURCE = "generatedVersionShareByMajor";
+    private static final String JSON_DATA = "{\"4\":0.000092,\"39\":0.004796,\"40\":0.004796,\"41\":0.009592,\"42\":0.004796,\"43\":0.004796,\"44\":0.004796,\"45\":0.009592,\"46\":0.004796,\"47\":0.009592,\"48\":0.014388,\"49\":0.014388,\"50\":0.009592,\"51\":0.009592,\"52\":0.014388,\"53\":0.009592,\"54\":0.004796,\"55\":0.009592,\"56\":0.009592,\"57\":0.009592,\"58\":0.009592,\"59\":0.009592,\"60\":0.014388,\"61\":0.004796,\"62\":0.009592,\"63\":0.009592,\"64\":0.009592,\"65\":0.004796,\"66\":0.02398,\"67\":0.009592,\"68\":0.009592,\"69\":0.033572,\"70\":0.009592,\"75\":0.004796,\"77\":0.004796,\"79\":0.067144,\"80\":0.009592,\"81\":0.009592,\"83\":0.043164,\"85\":0.004796,\"86\":0.009592,\"87\":0.028776,\"88\":0.004796,\"91\":0.019184,\"92\":0.014388,\"93\":0.009592,\"97\":0.009592,\"98\":0.04796,\"99\":0.043164,\"101\":0.014388,\"102\":0.009592,\"103\":0.26378,\"104\":0.230208,\"105\":0.273372,\"106\":0.206228,\"107\":0.230208,\"108\":0.230208,\"109\":0.786544,\"110\":0.235004,\"111\":0.292556,\"112\":2.71454,\"113\":0.004796,\"114\":0.062348,\"115\":0.02398,\"116\":0.446028,\"117\":0.282964,\"118\":0.052756,\"119\":0.038368,\"120\":0.31174,\"121\":0.04796,\"122\":0.091124,\"123\":0.062348,\"124\":0.230208,\"125\":0.244596,\"126\":0.052756,\"127\":0.052756,\"128\":0.076736,\"129\":0.067144,\"130\":0.09592,\"131\":0.709808,\"132\":0.139084,\"133\":0.52756,\"134\":0.067144,\"135\":0.067144,\"136\":0.09592,\"137\":0.062348,\"138\":0.235004,\"139\":3.34761,\"140\":0.177452,\"141\":0.398068,\"142\":1.29972,\"143\":10.4121,\"144\":3.76486,\"145\":41.8835}";
+
+    private GeneratedVersionShareData() {}
+
+    static JSONObject getDefaultVersionShareByMajor() {
+        try {
+            return new JSONObject(JSON_DATA);
+        } catch (Exception ignored) {
+            return new JSONObject();
+        }
+    }
+
+    static String getDataSource() {
+        return DATA_SOURCE;
+    }
+
+    static String getGeneratedAt() {
+        return GENERATED_AT;
+    }
+}