Capacitor Android customScheme issue with Chrome 117

On September 27th, Google published version 117 of the Android Webview to general availability. After this release, we were made aware that some Capacitor applications were reporting erroneous behavior, including hanging on application load. After investigating the changes in this release of the Webview, we identified that a change was made to the History API in this version that affects Capacitor applications using a custom scheme on Android. The result of this change is that custom schemes on Android can no longer change the URL path, which may prevent your application from routing correctly, making it appear to hang on load when routing fails.

Understanding the Impact

Out of the box, Capacitor 5 and earlier runs your Android application using the http scheme, while Capacitor 6 will use https. Both of these schemes are still valid and are verified to continue to work with Webview 117. If you are using either of these schemes explicitly, or are relying on the default values provided by Capacitor, you should be unaffected by this change and no action is required for your application.

If you are providing a custom value to androidScheme in your Capacitor Configuration file that is not http or https, it is likely that you may be impacted by this change. We would highly encourage you to test your application against Webview 117 to understand how this change will affect your application.

Updating Your Application

For anyone impacted by this change, we would strongly recommend that you change your androidScheme to use https. Please note that changing the scheme is the equivalent to shipping your application on a different domain, which means any data stored in cookies, localstorage, etc would no longer be accessible. Making this change will align your application with best practices recommended by both the Capacitor team as well as the Android team.

If changing your scheme is not possible for your circumstances, the other alternative is to switch your application to use a hash-based routing strategy. While custom schemes are no longer allowed to change the URL path in Webview 117, they are still allowed to change query parameters or hash fragments. This approach can work as a temporary solution, however we do not recommend relying on this long-term.

We understand that these changes may necessitate some adjustments to your application, but they are essential to ensure the continued reliability and performance of your applications.

If you have any questions or require further assistance, please do not hesitate to reach out to our support team through the forum or Discord.