@capgo/capacitor-webview-version-checker 8.0.0

package/README.md

@@ -0,0 +1,393 @@
+# @capgo/capacitor-webview-version-checker
+ <a href="https://capgo.app/"><img src='https://raw.githubusercontent.com/Cap-go/capgo/main/assets/capgo_banner.png' alt='Capgo - Instant updates for capacitor'/></a>
+
+<div align="center">
+  <h2><a href="https://capgo.app/?ref=plugin_webview_version_checker"> ➡️ Get Instant updates for your App with Capgo</a></h2>
+  <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.
+
+## Install
+
+```bash
+bun add @capgo/capacitor-webview-version-checker
+bunx cap sync
+```
+
+## Usage
+
+Simple setup (config only):
+
+```ts
+import type { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  plugins: {
+    WebviewVersionChecker: {
+      autoCheckOnLoad: true,
+      autoCheckOnResume: true,
+      autoPromptOnOutdated: true,
+    },
+  },
+};
+
+export default config;
+```
+
+Advanced usage with JavaScript (manual check, listeners, custom prompt):
+
+```ts
+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,
+  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();
+```
+
+## Why WebView Version Checker?
+
+Capacitor already provides a built-in WebView minimum check through config:
+
+```ts
+import type { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  android: {
+    minWebViewVersion: 124,
+  },
+  server: {
+    errorPath: 'unsupported-webview.html',
+  },
+};
+
+export default config;
+```
+
+### Why we're doing this instead
+
+- `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.
+
+## Android Provider Handling
+
+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.
+
+## API
+
+<docgen-index>
+
+* [`check(...)`](#check)
+* [`startMonitoring(...)`](#startmonitoring)
+* [`stopMonitoring()`](#stopmonitoring)
+* [`getLastStatus()`](#getlaststatus)
+* [`showUpdatePrompt(...)`](#showupdateprompt)
+* [`openUpdatePage(...)`](#openupdatepage)
+* [`addListener('statusChanged', ...)`](#addlistenerstatuschanged-)
+* [`addListener('webViewLatest', ...)`](#addlistenerwebviewlatest-)
+* [`addListener('webViewOutdated', ...)`](#addlistenerwebviewoutdated-)
+* [Interfaces](#interfaces)
+* [Type Aliases](#type-aliases)
+
+</docgen-index>
+
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+Public API for checking WebView freshness and guiding users to updates.
+
+### check(...)
+
+```typescript
+check(options?: CheckWebViewOptions | undefined) => Promise<WebViewVersionStatus>
+```
+
+Runs a version check and returns the latest known status.
+
+| Param         | Type                                                                |
+| ------------- | ------------------------------------------------------------------- |
+| **`options`** | <code><a href="#checkwebviewoptions">CheckWebViewOptions</a></code> |
+
+**Returns:** <code>Promise&lt;<a href="#webviewversionstatus">WebViewVersionStatus</a>&gt;</code>
+
+--------------------
+
+
+### startMonitoring(...)
+
+```typescript
+startMonitoring(options?: StartMonitoringOptions | undefined) => Promise<MonitoringStateResult>
+```
+
+Enables background monitoring (typically on app resume).
+
+| Param         | Type                                                                      |
+| ------------- | ------------------------------------------------------------------------- |
+| **`options`** | <code><a href="#startmonitoringoptions">StartMonitoringOptions</a></code> |
+
+**Returns:** <code>Promise&lt;<a href="#monitoringstateresult">MonitoringStateResult</a>&gt;</code>
+
+--------------------
+
+
+### stopMonitoring()
+
+```typescript
+stopMonitoring() => Promise<MonitoringStateResult>
+```
+
+Disables monitoring.
+
+**Returns:** <code>Promise&lt;<a href="#monitoringstateresult">MonitoringStateResult</a>&gt;</code>
+
+--------------------
+
+
+### getLastStatus()
+
+```typescript
+getLastStatus() => Promise<LastStatusResult>
+```
+
+Returns the last resolved status, or `null` if no check was run yet.
+
+**Returns:** <code>Promise&lt;<a href="#laststatusresult">LastStatusResult</a>&gt;</code>
+
+--------------------
+
+
+### showUpdatePrompt(...)
+
+```typescript
+showUpdatePrompt(options?: ShowUpdatePromptOptions | undefined) => Promise<ShowUpdatePromptResult>
+```
+
+Shows a native prompt asking the user to update the WebView.
+
+| Param         | Type                                                                        |
+| ------------- | --------------------------------------------------------------------------- |
+| **`options`** | <code><a href="#showupdatepromptoptions">ShowUpdatePromptOptions</a></code> |
+
+**Returns:** <code>Promise&lt;<a href="#showupdatepromptresult">ShowUpdatePromptResult</a>&gt;</code>
+
+--------------------
+
+
+### openUpdatePage(...)
+
+```typescript
+openUpdatePage(options?: OpenUpdatePageOptions | undefined) => Promise<OpenUpdatePageResult>
+```
+
+Opens the configured update page directly.
+
+| Param         | Type                                                                    |
+| ------------- | ----------------------------------------------------------------------- |
+| **`options`** | <code><a href="#openupdatepageoptions">OpenUpdatePageOptions</a></code> |
+
+**Returns:** <code>Promise&lt;<a href="#openupdatepageresult">OpenUpdatePageResult</a>&gt;</code>
+
+--------------------
+
+
+### addListener('statusChanged', ...)
+
+```typescript
+addListener(eventName: 'statusChanged', listenerFunc: (status: WebViewVersionStatus) => void) => Promise<PluginListenerHandle>
+```
+
+Fired for every successful status evaluation.
+
+| Param              | Type                                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------ |
+| **`eventName`**    | <code>'statusChanged'</code>                                                               |
+| **`listenerFunc`** | <code>(status: <a href="#webviewversionstatus">WebViewVersionStatus</a>) =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+--------------------
+
+
+### addListener('webViewLatest', ...)
+
+```typescript
+addListener(eventName: 'webViewLatest', listenerFunc: (status: WebViewVersionStatus) => void) => Promise<PluginListenerHandle>
+```
+
+Fired when the state resolves to `latest`.
+
+| Param              | Type                                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------ |
+| **`eventName`**    | <code>'webViewLatest'</code>                                                               |
+| **`listenerFunc`** | <code>(status: <a href="#webviewversionstatus">WebViewVersionStatus</a>) =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+--------------------
+
+
+### addListener('webViewOutdated', ...)
+
+```typescript
+addListener(eventName: 'webViewOutdated', listenerFunc: (status: WebViewVersionStatus) => void) => Promise<PluginListenerHandle>
+```
+
+Fired when the state resolves to `outdated`.
+
+| Param              | Type                                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------ |
+| **`eventName`**    | <code>'webViewOutdated'</code>                                                             |
+| **`listenerFunc`** | <code>(status: <a href="#webviewversionstatus">WebViewVersionStatus</a>) =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+--------------------
+
+
+### Interfaces
+
+
+#### WebViewVersionStatus
+
+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. |
+
+
+#### CheckWebViewOptions
+
+Options for running a WebView version check.
+
+| Prop                       | Type                 | Description                                                                       | Default               |
+| -------------------------- | -------------------- | --------------------------------------------------------------------------------- | --------------------- |
+| **`showPromptOnOutdated`** | <code>boolean</code> | Force showing a native prompt if an outdated WebView is detected.                 | <code>false</code>    |
+| **`source`**               | <code>string</code>  | Optional tag included in the status payload so you can identify the check origin. | <code>"manual"</code> |
+
+
+#### MonitoringStateResult
+
+Result payload for monitor controls.
+
+| Prop                       | Type                 | Description                                                  |
+| -------------------------- | -------------------- | ------------------------------------------------------------ |
+| **`monitoring`**           | <code>boolean</code> | Whether monitoring is currently active.                      |
+| **`checkOnResume`**        | <code>boolean</code> | Whether checks run on app resume while monitoring is active. |
+| **`autoPromptOnOutdated`** | <code>boolean</code> | Whether outdated checks auto-trigger the native prompt.      |
+
+
+#### StartMonitoringOptions
+
+Options for starting monitor mode.
+
+| Prop                | Type                 | Description                                                       | Default           |
+| ------------------- | -------------------- | ----------------------------------------------------------------- | ----------------- |
+| **`checkOnStart`**  | <code>boolean</code> | Run a check immediately when monitoring starts.                   | <code>true</code> |
+| **`checkOnResume`** | <code>boolean</code> | Whether foreground checks should run while monitoring is enabled. | <code>true</code> |
+
+
+#### LastStatusResult
+
+Last known check snapshot.
+
+| Prop         | Type                                                                          | Description                           |
+| ------------ | ----------------------------------------------------------------------------- | ------------------------------------- |
+| **`status`** | <code><a href="#webviewversionstatus">WebViewVersionStatus</a> \| null</code> | Null until the first check completes. |
+
+
+#### ShowUpdatePromptResult
+
+Result payload for `showUpdatePrompt()`.
+
+| Prop                   | Type                 | Description                                                |
+| ---------------------- | -------------------- | ---------------------------------------------------------- |
+| **`shown`**            | <code>boolean</code> | Whether a native prompt was actually shown.                |
+| **`openedUpdatePage`** | <code>boolean</code> | Whether the update page was opened from the prompt action. |
+
+
+#### ShowUpdatePromptOptions
+
+Options for showing the native update prompt.
+
+| Prop                   | Type                | Description                                            |
+| ---------------------- | ------------------- | ------------------------------------------------------ |
+| **`title`**            | <code>string</code> | Prompt title.                                          |
+| **`message`**          | <code>string</code> | Prompt message.                                        |
+| **`updateButtonText`** | <code>string</code> | Update CTA label.                                      |
+| **`cancelButtonText`** | <code>string</code> | Cancel CTA label.                                      |
+| **`updateUrl`**        | <code>string</code> | Optional URL to open if the update action is selected. |
+
+
+#### OpenUpdatePageResult
+
+Result payload for `openUpdatePage()`.
+
+| Prop         | Type                 | Description                               |
+| ------------ | -------------------- | ----------------------------------------- |
+| **`opened`** | <code>boolean</code> | Whether opening the update URL succeeded. |
+| **`url`**    | <code>string</code>  | URL that was attempted.                   |
+
+
+#### OpenUpdatePageOptions
+
+Options for opening the update page directly.
+
+| Prop            | Type                | Description            |
+| --------------- | ------------------- | ---------------------- |
+| **`updateUrl`** | <code>string</code> | Optional URL override. |
+
+
+#### PluginListenerHandle
+
+| Prop         | Type                                      |
+| ------------ | ----------------------------------------- |
+| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |
+
+
+### Type Aliases
+
+
+#### WebViewPlatform
+
+<code>'android' | 'ios' | 'web'</code>
+
+
+#### WebViewVersionState
+
+<code>'latest' | 'outdated' | 'unknown'</code>
+
+</docgen-api>

package/android/build.gradle

@@ -0,0 +1,61 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    androidxWebkitVersion = project.hasProperty('androidxWebkitVersion') ? rootProject.ext.androidxWebkitVersion : '1.14.0'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace = "app.capgo.webviewversionchecker"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+    lintOptions {
+        abortOnError = false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    annotationProcessor project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "androidx.webkit:webkit:$androidxWebkitVersion"
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.INTERNET" />
+</manifest>

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

@@ -0,0 +1,75 @@
+package app.capgo.webviewversionchecker;
+
+import androidx.annotation.Nullable;
+import java.util.ArrayList;
+import java.util.List;
+
+final class WebviewVersionChecker {
+
+    @Nullable
+    Integer parseMajorVersion(@Nullable String version) {
+        if (version == null || version.isEmpty()) {
+            return null;
+        }
+
+        StringBuilder digits = new StringBuilder();
+        for (int i = 0; i < version.length(); i++) {
+            char c = version.charAt(i);
+            if (Character.isDigit(c)) {
+                digits.append(c);
+            } else if (digits.length() > 0) {
+                break;
+            }
+        }
+
+        if (digits.length() == 0) {
+            return null;
+        }
+
+        try {
+            return Integer.parseInt(digits.toString());
+        } catch (NumberFormatException error) {
+            return null;
+        }
+    }
+
+    int compareVersions(@Nullable String left, @Nullable String right) {
+        List<Integer> leftParts = tokenize(left);
+        List<Integer> rightParts = tokenize(right);
+
+        int max = Math.max(leftParts.size(), rightParts.size());
+        for (int index = 0; index < max; index++) {
+            int a = index < leftParts.size() ? leftParts.get(index) : 0;
+            int b = index < rightParts.size() ? rightParts.get(index) : 0;
+            if (a > b) {
+                return 1;
+            }
+            if (a < b) {
+                return -1;
+            }
+        }
+
+        return 0;
+    }
+
+    private List<Integer> tokenize(@Nullable String value) {
+        List<Integer> out = new ArrayList<>();
+        if (value == null || value.isEmpty()) {
+            return out;
+        }
+
+        String[] rawParts = value.split("[^0-9]+");
+        for (String part : rawParts) {
+            if (part == null || part.isEmpty()) {
+                continue;
+            }
+            try {
+                out.add(Integer.parseInt(part));
+            } catch (NumberFormatException ignored) {
+                out.add(0);
+            }
+        }
+
+        return out;
+    }
+}