fix(android): fix loading of keyboards on Android by ermshiperete · Pull Request #16146 · keymanapp/keyman

ermshiperete · 2026-06-26T16:46:23Z

This PR migrates the Android WebView from loading local files via file:// URLs to using WebViewAssetLoader, which serves internal storage files through a magic HTTPS domain (https://appassets.androidplatform.net). This fixes the blank keyboard problem reported in #16096 for Android.

Core pattern of the change:

// Before:
"file://" + context.getDir("data", ...)
  + "/" + filename
// After:
"https://appassets.androidplatform.net"
  + "/data/" + filename

The WebViewAssetLoader in KMKeyboardWebViewClient intercepts requests to this domain and serves files from internal storage. Since the domain is a constant, Context is no longer needed to construct URLs, simplifying several method signatures.

Also this PR makes KMKeyboard.getKeyboardRoot() private, and renames public Keyboard.getKeyboardPath() to private Keyboard.getKeyboardUrl().

Part-of: #16096
Replaces: #16132

keymanapp-test-bot · 2026-06-26T16:46:28Z

User Test Results

Test specification and instructions

ERROR: user tests have not yet been defined

Test Artifacts

Android
- Keyman for Android apk - build : all tests passed (no artifacts on BuildLevel "build")
- FirstVoices Keyboards for Android apk - build : all tests passed (no artifacts on BuildLevel "build")
- FirstVoices Keyboards for Android apk (old PRs) - build : all tests passed (no artifacts on BuildLevel "build")
- KeyboardHarness apk - build : all tests passed (no artifacts on BuildLevel "build")
- Keyman for Android apk (old PRs) - build : all tests passed (no artifacts on BuildLevel "build")
- KMSample1 apk - build : all tests passed (no artifacts on BuildLevel "build")
- KMSample2 apk - build : all tests passed (no artifacts on BuildLevel "build")

This change moves to using `WebViewAssetLoader` for loading files from the device instead of using file:// URLs. This fixes the blank keyboard problem reported in #16096 for Android. Also make `KMKeyboard.getKeyboardRoot()` private, and rename public `Keyboard.getKeyboardPath()` to private `Keyboard.getKeyboardUrl()`. Part-of: #16096

jahorton · 2026-06-26T18:56:33Z

Also this PR makes KMKeyboard.getKeyboardRoot() private, and renames public Keyboard.getKeyboardPath() to private Keyboard.getKeyboardUrl().

Note that KMKeyboard is a part of our public API for Keyman Engine for Android. That said, .getKeyboardRoot() was never published. It may be worth seeing if Scripture App Builder or Keyboard App Builder were using it.

https://help.keyman.com/developer/engine/android/current-version/KMKeyboard/

jahorton

LGTM aside from the one nit.

jahorton · 2026-06-26T19:15:03Z

  }

-  public String getKeyboardRoot() {
+  private String getKeyboardRoot() {


We should probably leave this unchanged; KMKeyboard is an engine API class.

I asked the App Builder team about it, just in case; no effect for them at present.

This was an internal public, not a published API endpoint, can safely make private.

mcdurdin · 2026-06-29T07:07:24Z

Note that KMKeyboard is a part of our public API for Keyman Engine for Android.

If it's not documented, then it's not part of the API. It's a public method but an internal implementation detail.

mcdurdin

This is looking good, some tidyup and consolidation requested. Also have noted future work on KMDefault_UndefinedPackageID (we can turn that into a follow-up issue).

mcdurdin · 2026-06-29T07:10:36Z

    if (packageID.equals(KMManager.KMDefault_UndefinedPackageID)) {
-      return keyboardRoot + KMManager.KMDefault_UndefinedPackageID + File.separator;
+      keyboardRoot += KMManager.KMDefault_UndefinedPackageID + "/";
    } else {


I know this isn't new, I really wonder about the whole KMDefault_UndefinedPackageID (aka "cloud") pattern throughout this code. It seems like this is a fake "null" but I haven't fully audited its use. I would love to eliminate it altogether (28 references) because it seems like it is unnecessary complexity.

mcdurdin · 2026-06-29T07:12:39Z

  private static String txtFont = "";
  private static String oskFont = null;
-  private static String keyboardRoot = "";
+  private String keyboardRoot = "";


Why no longer static?

mcdurdin · 2026-06-29T07:14:16Z

    if (packageID.equals(KMManager.KMDefault_UndefinedPackageID)) {
-      this.keyboardRoot = (context.getDir("data", Context.MODE_PRIVATE).toString() +
-        File.separator + KMManager.KMDefault_UndefinedPackageID + File.separator);
+      this.keyboardRoot = WebViewUtils.MAGIC_DEFAULT_DOMAIN + "/data/" + KMManager.KMDefault_UndefinedPackageID + "/";


Suggested change

this.keyboardRoot = WebViewUtils.MAGIC_DEFAULT_DOMAIN + "/data/" + KMManager.KMDefault_UndefinedPackageID + "/";

this.keyboardRoot = WebViewUtils.buildAssetUrl(KMManager.KMDefault_UndefinedPackageID + "/");

Can we make a method under WebViewUtils which builds these URLs so we don't repeat the WebViewUtils.MAGIC_DEFAULT_DOMAIN + "/data/" pattern?

public String buildAssetUrl(String assetPath) { return WebViewUtils.MAGIC_DEFAULT_DOMAIN + "/data/" + assetPath; }

Or even:

Suggested change

this.keyboardRoot = WebViewUtils.MAGIC_DEFAULT_DOMAIN + "/data/" + KMManager.KMDefault_UndefinedPackageID + "/";

this.keyboardRoot = WebViewUtils.buildAssetUrl([KMManager.KMDefault_UndefinedPackageID, ""]);

public String buildAssetUrl(String[] assetPath) { return WebViewUtils.MAGIC_DEFAULT_DOMAIN + "/data/" + String.join("/", assetPath); }

mcdurdin · 2026-06-29T07:15:50Z

    } else {
-      this.keyboardRoot = (context.getDir("data", Context.MODE_PRIVATE).toString() +
-        File.separator + KMManager.KMDefault_AssetPackages + File.separator + packageID + File.separator);
+      this.keyboardRoot = WebViewUtils.MAGIC_DEFAULT_DOMAIN + "/data/" + KMManager.KMDefault_AssetPackages + "/" + packageID + "/";


Suggested change

this.keyboardRoot = WebViewUtils.MAGIC_DEFAULT_DOMAIN + "/data/" + KMManager.KMDefault_AssetPackages + "/" + packageID + "/";

this.keyboardRoot = WebViewUtils.buildAssetUrl(KMManager.KMDefault_AssetPackages + "/" + packageID + "/");

or

Suggested change

this.keyboardRoot = WebViewUtils.MAGIC_DEFAULT_DOMAIN + "/data/" + KMManager.KMDefault_AssetPackages + "/" + packageID + "/";

this.keyboardRoot = WebViewUtils.buildAssetUrl([KMManager.KMDefault_AssetPackages, packageID]);

mcdurdin · 2026-06-29T07:24:29Z

+  public static String getResourceUrl() {
+    return WebViewUtils.MAGIC_DEFAULT_DOMAIN +"/data/";
+  }


Use shared method in WebViewUtils instead as proposed

mcdurdin · 2026-06-29T07:25:11Z

  }

+  public static String getLexicalModelsUrl() {
+    return getResourceUrl() + KMDefault_LexicalModelPackages + "/";


Suggested change

return getResourceUrl() + KMDefault_LexicalModelPackages + "/";

return WebViewUtils.buildAssetUrl(KMDefault_LexicalModelPackages + "/");

or

Suggested change

return getResourceUrl() + KMDefault_LexicalModelPackages + "/";

return WebViewUtils.buildAssetUrl([KMDefault_LexicalModelPackages, ""]);

mcdurdin · 2026-06-29T07:26:53Z

-    String htmlPath = "file://" + getContext().getDir("data", Context.MODE_PRIVATE) + "/" + KMManager.KMFilename_KeyboardHtml;
+    // Use the reserved magic domain for loading the keyboard from the local device.
+    // See https://developer.android.com/reference/androidx/webkit/WebViewAssetLoader
+    String htmlPath = WebViewUtils.MAGIC_DEFAULT_DOMAIN + "/data/" + KMManager.KMFilename_KeyboardHtml;


Suggested change

String htmlPath = WebViewUtils.MAGIC_DEFAULT_DOMAIN + "/data/" + KMManager.KMFilename_KeyboardHtml;

String htmlPath = WebViewUtils.buildAssetUrl(KMManager.KMFilename_KeyboardHtml);

or

Suggested change

String htmlPath = WebViewUtils.MAGIC_DEFAULT_DOMAIN + "/data/" + KMManager.KMFilename_KeyboardHtml;

String htmlPath = WebViewUtils.buildAssetUrl([KMManager.KMFilename_KeyboardHtml]);

mcdurdin · 2026-06-29T07:27:16Z

+    // Use the reserved magic domain for loading the keyboard from the local device.
+    // See https://developer.android.com/reference/androidx/webkit/WebViewAssetLoader


This comment can just go in WebViewUtils.java, buildAssertUrl()

mcdurdin · 2026-06-29T07:30:06Z

+   * internal storage path.
+   * See https://developer.android.com/reference/androidx/webkit/WebViewAssetLoader
+   */
+  public static final String MAGIC_DEFAULT_DOMAIN = "https://appassets.androidplatform.net";


Suggested change

public static final String MAGIC_DEFAULT_DOMAIN = "https://appassets.androidplatform.net";

private static final String MAGIC_DEFAULT_DOMAIN = "https://appassets.androidplatform.net";

/**

* Path under the asset domain where all assets live

*/

public static final String ASSET_DATA_PATH = "/data/";

/**

* Build a full URL to the provided asset

*/

public String buildAssetUrl(String assetPath) {

return WebViewUtils.MAGIC_DEFAULT_DOMAIN + WebViewUtils.ASSET_DATA_PATH + assetPath;

}

or

Suggested change

public static final String MAGIC_DEFAULT_DOMAIN = "https://appassets.androidplatform.net";

private static final String MAGIC_DEFAULT_DOMAIN = "https://appassets.androidplatform.net";

/**

* Path under the asset domain where all assets live

*/

public static final String ASSET_DATA_PATH = "/data/";

/**

* Build a full URL to the provided asset, joining all components with '/'

*/

public String buildAssetUrl(String[] assetPath) {

return WebViewUtils.MAGIC_DEFAULT_DOMAIN + WebViewUtils.ASSET_DATA_PATH + String.join("/", assetPath);

}

github-project-automation Bot added this to Keyman Jun 26, 2026

github-project-automation Bot moved this to Todo in Keyman Jun 26, 2026

keymanapp-test-bot Bot added the user-test-missing User tests have not yet been defined for the PR label Jun 26, 2026

keymanapp-test-bot Bot added this to the A19S32 milestone Jun 26, 2026

github-actions Bot added android/ android/engine/ android/app/ fix labels Jun 26, 2026

ermshiperete mentioned this pull request Jun 26, 2026

fix(web): allow to use file URLs on Android #16132

Draft

ermshiperete force-pushed the fix/android/16096_blankKeyboard branch from f317db4 to b406759 Compare June 26, 2026 17:38

ermshiperete force-pushed the fix/android/16096_blankKeyboard branch from b406759 to 64abd5b Compare June 26, 2026 18:02

ermshiperete requested review from jahorton and mcdurdin June 26, 2026 18:04

ermshiperete marked this pull request as ready for review June 26, 2026 18:10

jahorton approved these changes Jun 26, 2026

View reviewed changes

mcdurdin requested changes Jun 29, 2026

View reviewed changes

	this.keyboardRoot = WebViewUtils.MAGIC_DEFAULT_DOMAIN + "/data/" + KMManager.KMDefault_UndefinedPackageID + "/";
	this.keyboardRoot = WebViewUtils.buildAssetUrl(KMManager.KMDefault_UndefinedPackageID + "/");

	return getResourceUrl() + KMDefault_LexicalModelPackages + "/";
	return WebViewUtils.buildAssetUrl(KMDefault_LexicalModelPackages + "/");

	return getResourceUrl() + KMDefault_LexicalModelPackages + "/";
	return WebViewUtils.buildAssetUrl([KMDefault_LexicalModelPackages, ""]);

	String htmlPath = WebViewUtils.MAGIC_DEFAULT_DOMAIN + "/data/" + KMManager.KMFilename_KeyboardHtml;
	String htmlPath = WebViewUtils.buildAssetUrl(KMManager.KMFilename_KeyboardHtml);

		// Use the reserved magic domain for loading the keyboard from the local device.
		// See https://developer.android.com/reference/androidx/webkit/WebViewAssetLoader

-  public static final String MAGIC_DEFAULT_DOMAIN = "https://appassets.androidplatform.net";
+  private static final String MAGIC_DEFAULT_DOMAIN = "https://appassets.androidplatform.net";
+  /**
+   * Path under the asset domain where all assets live
+   */
+  public static final String ASSET_DATA_PATH = "/data/";
+  /**
+   * Build a full URL to the provided asset
+   */
+  public String buildAssetUrl(String assetPath) {
+    return WebViewUtils.MAGIC_DEFAULT_DOMAIN + WebViewUtils.ASSET_DATA_PATH + assetPath;
+  }

Uh oh!

Uh oh!

Conversation

ermshiperete commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

keymanapp-test-bot Bot commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User Test Results

Test Artifacts

Uh oh!

jahorton commented Jun 26, 2026

Uh oh!

jahorton left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcdurdin commented Jun 29, 2026

Uh oh!

mcdurdin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ermshiperete commented Jun 26, 2026 •

edited

Loading

keymanapp-test-bot Bot commented Jun 26, 2026 •

edited

Loading