feat: add web view version check by preference AndroidMinimumWebViewVersion

[GitToTheHub]

Platforms affected

Android

Motivation and Context

I often had the problem when deploying an Android app to an older emulator like Android version 7/8/9, where the WebView does not update in the emulator and using more recent JavaScript features like for e.g. optional chaining ?. which is available in Chrome 80, i got stuck in the splash screen and nothing happens. I also didn't see a JS alert, when I tried to catch errors. I tried to solve this in JS by checking the web view before, but I would have to check the web view version first and the had to load all scripts after, which is not a nice solution. Also, this feature could be made available more easy for others in this way.

Description

• If preference AndroidMinimumWebViewVersion is set, it will check if the current installed web view suits the version. If not, an error message is shown and the app exists, after the user clicks on OK.
• The strings can be internationalized by adding a strings.xml with appropriates strings to the appropriate values directory.
• Generated-By: Claude Haiku 4.5, Visual Studio Code

Overview of WebView Version Check Feature - Generated by Claude Haiku 4.5

Overview

This feature adds support for enforcing a minimum WebView version requirement in Cordova Android apps. If the installed WebView version is older than the specified minimum, a dialog will be shown to the user prompting them to update through the Google Play Store, and the app will close.

Usage

1. Add the Preference to config.xml

Add the AndroidMinimumWebViewVersion preference to your config.xml file:

<?xml version='1.0' encoding='utf-8'?>
<widget id="io.cordova.hellocordova" version="1.0.0"
        xmlns="http://www.w3.org/ns/widgets">
    <name>Hello Cordova</name>
    
    <!-- Set minimum WebView version to 80.0 -->
    <preference name="AndroidMinimumWebViewVersion" value="80.0" />
    
    <!-- ... rest of config.xml ... -->
</widget>

2. Version Format

• The version string should start with the major version number: "80.0", "90.0", "100.0", etc.
• You can use full versions with patch numbers: "80.0.1234.56" - only the relevant parts will be compared
• The comparison is done numerically, part-by-part (e.g., 80.0 < 90.0 < 100.0)

3. What Happens

If a user's WebView version is too old:

1. A dialog appears with the title: "WebView Update Required"
2. Message: "Your Android System WebView version is too old. Please update it through the Google Play Store."
3. An "OK" button closes the dialog and exits the app
4. The user must update their WebView before they can use the app

4. Internationalization

The strings used in the dialog can be customized by overriding the string resources in your project's res/values/ directory:

<!-- res/values/strings.xml -->
<string name="webview_version_too_old_title">Your Custom Title</string>
<string name="webview_version_too_old_message">Your custom message here</string>
<string name="webview_version_ok_button">Continue</string>

For other languages, create localized versions:

<!-- res/values-de/strings.xml (German) -->
<string name="webview_version_too_old_title">WebView-Update erforderlich</string>
<string name="webview_version_too_old_message">Ihre Android System WebView-Version ist zu alt. Bitte aktualisieren Sie sie über den Google Play Store.</string>
<string name="webview_version_ok_button">OK</string>

<!-- res/values-fr/strings.xml (French) -->
<string name="webview_version_too_old_title">Mise à jour de WebView requise</string>
<string name="webview_version_too_old_message">Votre version Android System WebView est trop ancienne. Veuillez la mettre à jour via le Google Play Store.</string>
<string name="webview_version_ok_button">OK</string>

5. Examples

Example 1: Require WebView 80.0 or newer

<preference name="AndroidMinimumWebViewVersion" value="80.0" />

Example 2: Require WebView 100.0 with specific patch

<preference name="AndroidMinimumWebViewVersion" value="100.0.4896.26" />

Example 3: No version requirement (feature disabled)

<!-- Omit the preference entirely or leave it empty -->
<!-- No dialog will be shown -->

Technical Details

How it Works

1. Version Detection: The feature uses WebViewCompat.getCurrentWebViewPackage() (API 26+) to get the installed WebView package, or falls back to querying the com.google.android.webview package directly
2. Version Comparison: Versions are parsed and compared numerically, part by part (e.g., 80.0.1234 is compared as [80, 0, 1234])
3. Timing: The check is performed in CordovaActivity.onCreate() after preferences are loaded but before any WebView content is loaded
4. Dialog: Uses Android's standard AlertDialog for the warning message

Error Handling

• If the WebView version cannot be determined, the check is skipped (app continues normally)
• If version parsing fails, the app assumes the version is acceptable and continues
• All exceptions during the check are caught and logged

Supported Android Versions

This feature works on all supported Android versions. The WebView version checking uses Android 8+ optimized methods when available, with graceful fallbacks for older API levels.

Implementation Files Changed

1. CordovaActivity.java - Added WebView version checking logic
2. cdv_strings.xml - Added localized string resources for the dialog (optional - defaults are built-in)

API Details

The implementation includes four new private methods in CordovaActivity:

• checkWebViewVersion() - Main method called from onCreate
• getWebViewVersion() - Retrieves the current WebView version string
• isWebViewVersionSufficient() - Compares version strings
• getWebViewVersionTitle(), getWebViewVersionMessage(), getWebViewVersionButtonText() - Get localized strings with fallback defaults

String Customization

The dialog strings can be customized in three ways (in order of precedence):

1. Via app's string resources (highest priority):

   • Add webview_version_too_old_title, webview_version_too_old_message, webview_version_ok_button to your app's res/values/strings.xml

2. Via template string resources:

   • Defined in cordova-android/templates/project/res/values/cdv_strings.xml
   • These are used when building new projects from the template

3. Built-in defaults (lowest priority):

   • Default English strings are hardcoded in CordovaActivity if resources are not found
   • Title: "WebView Update Required"
   • Message: "Your Android System WebView version is too old. Please update it through the Google Play Store."
   • Button: "OK"

Testing

• Tested on Android 9 with WebView 66 and using WebView 80 features and setting <preference name="AndroidMinimumWebViewVersion" value="80.0" />

Checklist

• I've run the tests to see all new and existing tests pass
• I added automated test coverage as appropriate for this change
• Commit is prefixed with (platform) if this change only applies to one platform (e.g. (android))
• If this Pull Request resolves an issue, I linked to the issue in the text above (and used the correct keyword to close issues using keywords)
• I've updated the documentation if necessary

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 61.43%. Comparing base (c02d1b0) to head (bc2d92e).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1901   +/-   ##
=======================================
  Coverage   61.43%   61.43%           
=======================================
  Files          24       24           
  Lines        4922     4922           
=======================================
  Hits         3024     3024           
  Misses       1898     1898           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[erisu]

This is just my opinion, but I feel this might work better as a plugin rather than something included directly in the core library.

I understand the concern where users might use modern JavaScript that may not be supported in older WebViews, and that users should be made aware of this.

But, I would be interested in hearing what others think about where this should reside.

For example, what if people begin asking for the ability to custom design the dialog so it could match their app's design? Or add various buttons that might do a certain function in those scenarios. I'm curious how large this could become to support and maintain within the core library. If it was a plugin, app developers can fork and manipulate easily the design if needed.

[breautek]

We aren't suppose to assume the underlying webview implementation. It might not even be chrome-based or the system webview component. It could be someone's completely custom webview component for example. And I feel like this new preference assumes a particular webview implementation.

So for that reason, like Erisu, I think this might be better off as a plugin rather than a core feature.

[GitToTheHub]

We aren't suppose to assume the underlying webview implementation. It might not even be chrome-based or the system webview component. It could be someone's completely custom webview component for example. And I feel like this new preference assumes a particular webview implementation.

Ok I didn't know, that the WebView could be changed. I could rename AndroidMinimumWebViewVersion to AndroidMinimumChromiumVersion. But if you both think, this should be more a plugin, then I'm outvoted :D