* For more context about application's assets and resources and how to normally access them please * refer to * Android Developer Docs: App resources overview. * *
* This class is expected to be used within * {@link android.webkit.WebViewClient#shouldInterceptRequest}, which is invoked on a different * thread than application's main thread. Although instances are themselves thread-safe (and may be * safely constructed on the application's main thread), exercise caution when accessing private * data or the view system. *
* Using http(s):// URLs to access local resources may conflict with a real website. This means * that local files should only be hosted on domains your organization owns (at paths reserved * for this purpose) or the default domain reserved for this: {@code appassets.androidplatform.net}. *
* A typical usage would be like: *
* final WebViewAssetLoader assetLoader = new WebViewAssetLoader.Builder()
* .addPathHandler("/assets/", new AssetsPathHandler(this))
* .build();
*
* webView.setWebViewClient(new WebViewClientCompat() {
* {@literal @}Override
* {@literal @}RequiresApi(21)
* public WebResourceResponse shouldInterceptRequest(WebView view, WebResourceRequest request) {
* return assetLoader.shouldInterceptRequest(request.getUrl());
* }
*
* {@literal @}Override
* {@literal @}SuppressWarnings("deprecation") // for API < 21
* public WebResourceResponse shouldInterceptRequest(WebView view, String url) {
* return assetLoader.shouldInterceptRequest(Uri.parse(url));
* }
* });
*
* WebSettings webViewSettings = webView.getSettings();
* // Setting this off for security. Off by default for SDK versions >= 16.
* webViewSettings.setAllowFileAccessFromFileURLs(false);
* // Off by default, deprecated for SDK versions >= 30.
* webViewSettings.setAllowUniversalAccessFromFileURLs(false);
* // Keeping these off is less critical but still a good idea, especially if your app is not
* // using file:// or content:// URLs.
* webViewSettings.setAllowFileAccess(false);
* webViewSettings.setAllowContentAccess(false);
*
* // Assets are hosted under http(s)://appassets.androidplatform.net/assets/... .
* // If the application's assets are in the "main/assets" folder this will read the file
* // from "main/assets/www/index.html" and load it as if it were hosted on:
* // https://appassets.androidplatform.net/assets/www/index.html
* webview.loadUrl("https://appassets.androidplatform.net/assets/www/index.html");
*
*/
public final class WebViewAssetLoader {
private static final String TAG = "WebViewAssetLoader";
/**
* An unused domain reserved for Android applications to intercept requests for app assets.
*
* It is used by default unless the user specified a different domain.
*/
public static final String DEFAULT_DOMAIN = "appassets.androidplatform.net";
private final List
* Implement this interface to handle other use-cases according to your app's needs.
*
* Methods of this handler will be invoked on a background thread and care must be taken to
* correctly synchronize access to any shared state.
*
* On Android KitKat and above these methods may be called on more than one thread. This thread
* may be different than the thread on which the shouldInterceptRequest method was invoked.
* This means that on Android KitKat and above it is possible to block in this method without
* blocking other resources from loading. The number of threads used to parallelize loading
* is an internal implementation detail of the WebView and may change between updates which
* means that the amount of time spent blocking in this method should be kept to an absolute
* minimum.
*/
public interface PathHandler {
/**
* Handles the requested URL by returning the appropriate response.
*
* Returning a {@code null} value means that the handler decided not to handle this path.
* In this case, {@link WebViewAssetLoader} will try the next handler registered on this
* path or pass to WebView that will fall back to network to try to resolve the URL.
*
* However, if the handler wants to save unnecessary processing either by another handler or
* by falling back to network, in cases like a file cannot be found, it may return a
* {@code new WebResourceResponse(null, null, null)} which is received as an
* HTTP response with status code {@code 404} and no body.
*
* @param path the suffix path to be handled.
* @return {@link WebResourceResponse} for the requested path or {@code null} if it can't
* handle this path.
*/
@WorkerThread
@Nullable
WebResourceResponse handle(@NonNull String path);
}
/**
* Handler class to open a file from assets directory in the application APK.
*/
public static final class AssetsPathHandler implements PathHandler {
private AssetHelper mAssetHelper;
/**
* @param context {@link Context} used to resolve assets.
*/
public AssetsPathHandler(@NonNull Context context) {
mAssetHelper = new AssetHelper(context);
}
@VisibleForTesting
/*package*/ AssetsPathHandler(@NonNull AssetHelper assetHelper) {
mAssetHelper = assetHelper;
}
/**
* Opens the requested file from the application's assets directory.
*
* The matched prefix path used shouldn't be a prefix of a real web path. Thus, if the
* requested file cannot be found a {@link WebResourceResponse} object with a {@code null}
* {@link InputStream} will be returned instead of {@code null}. This saves the time of
* falling back to network and trying to resolve a path that doesn't exist. A
* {@link WebResourceResponse} with {@code null} {@link InputStream} will be received as an
* HTTP response with status code {@code 404} and no body.
*
* The MIME type for the file will be determined from the file's extension using
* {@link java.net.URLConnection#guessContentTypeFromName}. Developers should ensure that
* asset files are named using standard file extensions. If the file does not have a
* recognised extension, {@code "text/plain"} will be used by default.
*
* @param path the suffix path to be handled.
* @return {@link WebResourceResponse} for the requested file.
*/
@Override
@WorkerThread
@Nullable
public WebResourceResponse handle(@NonNull String path) {
try {
InputStream is = mAssetHelper.openAsset(path);
String mimeType = AssetHelper.guessMimeType(path);
return new WebResourceResponse(mimeType, null, is);
} catch (IOException e) {
Log.e(TAG, "Error opening asset path: " + path, e);
return new WebResourceResponse(null, null, null);
}
}
}
/**
* Handler class to open a file from resources directory in the application APK.
*/
public static final class ResourcesPathHandler implements PathHandler {
private AssetHelper mAssetHelper;
/**
* @param context {@link Context} used to resolve resources.
*/
public ResourcesPathHandler(@NonNull Context context) {
mAssetHelper = new AssetHelper(context);
}
@VisibleForTesting
/*package*/ ResourcesPathHandler(@NonNull AssetHelper assetHelper) {
mAssetHelper = assetHelper;
}
/**
* Opens the requested file from application's resources directory.
*
* The matched prefix path used shouldn't be a prefix of a real web path. Thus, if the
* requested file cannot be found a {@link WebResourceResponse} object with a {@code null}
* {@link InputStream} will be returned instead of {@code null}. This saves the time of
* falling back to network and trying to resolve a path that doesn't exist. A
* {@link WebResourceResponse} with {@code null} {@link InputStream} will be received as an
* HTTP response with status code {@code 404} and no body.
*
* The MIME type for the file will be determined from the file's extension using
* {@link java.net.URLConnection#guessContentTypeFromName}. Developers should ensure that
* resource files are named using standard file extensions. If the file does not have a
* recognised extension, {@code "text/plain"} will be used by default.
*
* @param path the suffix path to be handled.
* @return {@link WebResourceResponse} for the requested file.
*/
@Override
@WorkerThread
@Nullable
public WebResourceResponse handle(@NonNull String path) {
try {
InputStream is = mAssetHelper.openResource(path);
String mimeType = AssetHelper.guessMimeType(path);
return new WebResourceResponse(mimeType, null, is);
} catch (Resources.NotFoundException e) {
Log.e(TAG, "Resource not found from the path: " + path, e);
} catch (IOException e) {
Log.e(TAG, "Error opening resource from the path: " + path, e);
}
return new WebResourceResponse(null, null, null);
}
}
/**
* Handler class to open files from application internal storage.
* For more information about android storage please refer to
* Android Developers
* Docs: Data and file storage overview.
*
* To avoid leaking user or app data to the web, make sure to choose {@code directory}
* carefully, and assume any file under this directory could be accessed by any web page subject
* to same-origin rules.
*
* A typical usage would be like:
*
* Note: Any future addition to this list will be considered breaking changes to the API.
*/
private static final String[] FORBIDDEN_DATA_DIRS =
new String[] {"app_webview/", "databases/", "lib/", "shared_prefs/", "code_cache/"};
@NonNull private final File mDirectory;
/**
* Creates PathHandler for app's internal storage.
* The directory to be exposed must be inside either the application's internal data
* directory {@link Context#getDataDir} or cache directory {@link Context#getCacheDir}.
* External storage is not supported for security reasons, as other apps with
* {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} may be able to modify the
* files.
*
* Exposing the entire data or cache directory is not permitted, to avoid accidentally
* exposing sensitive application files to the web. Certain existing subdirectories of
* {@link Context#getDataDir} are also not permitted as they are often sensitive.
* These files are ({@code "app_webview/"}, {@code "databases/"}, {@code "lib/"},
* {@code "shared_prefs/"} and {@code "code_cache/"}).
*
* The application should typically use a dedicated subdirectory for the files it intends to
* expose and keep them separate from other files.
*
* @param context {@link Context} that is used to access app's internal storage.
* @param directory the absolute path of the exposed app internal storage directory from
* which files can be loaded.
* @throws IllegalArgumentException if the directory is not allowed.
*/
public InternalStoragePathHandler(@NonNull Context context, @NonNull File directory) {
try {
mDirectory = new File(AssetHelper.getCanonicalDirPath(directory));
if (!isAllowedInternalStorageDir(context)) {
throw new IllegalArgumentException("The given directory \"" + directory
+ "\" doesn't exist under an allowed app internal storage directory");
}
} catch (IOException e) {
throw new IllegalArgumentException(
"Failed to resolve the canonical path for the given directory: "
+ directory.getPath(), e);
}
}
private boolean isAllowedInternalStorageDir(@NonNull Context context) throws IOException {
String dir = AssetHelper.getCanonicalDirPath(mDirectory);
String cacheDir = AssetHelper.getCanonicalDirPath(context.getCacheDir());
String dataDir = AssetHelper.getCanonicalDirPath(AssetHelper.getDataDir(context));
// dir has to be a subdirectory of data or cache dir.
if (!dir.startsWith(cacheDir) && !dir.startsWith(dataDir)) {
return false;
}
// dir cannot be the entire cache or data dir.
if (dir.equals(cacheDir) || dir.equals(dataDir)) {
return false;
}
// dir cannot be a subdirectory of any forbidden data dir.
for (String forbiddenPath : FORBIDDEN_DATA_DIRS) {
if (dir.startsWith(dataDir + forbiddenPath)) {
return false;
}
}
return true;
}
/**
* Opens the requested file from the exposed data directory.
*
* The matched prefix path used shouldn't be a prefix of a real web path. Thus, if the
* requested file cannot be found or is outside the mounted directory a
* {@link WebResourceResponse} object with a {@code null} {@link InputStream} will be
* returned instead of {@code null}. This saves the time of falling back to network and
* trying to resolve a path that doesn't exist. A {@link WebResourceResponse} with
* {@code null} {@link InputStream} will be received as an HTTP response with status code
* {@code 404} and no body.
*
* The MIME type for the file will be determined from the file's extension using
* {@link java.net.URLConnection#guessContentTypeFromName}. Developers should ensure that
* files are named using standard file extensions. If the file does not have a
* recognised extension, {@code "text/plain"} will be used by default.
*
* @param path the suffix path to be handled.
* @return {@link WebResourceResponse} for the requested file.
*/
@Override
@WorkerThread
@NonNull
public WebResourceResponse handle(@NonNull String path) {
try {
File file = AssetHelper.getCanonicalFileIfChild(mDirectory, path);
if (file != null) {
InputStream is = AssetHelper.openFile(file);
String mimeType = AssetHelper.guessMimeType(path);
return new WebResourceResponse(mimeType, null, is);
} else {
Log.e(TAG, String.format(
"The requested file: %s is outside the mounted directory: %s", path,
mDirectory));
}
} catch (IOException e) {
Log.e(TAG, "Error opening the requested path: " + path, e);
}
return new WebResourceResponse(null, null, null);
}
}
/**
* Matches URIs on the form: {@code "http(s)://authority/path/**"}, HTTPS is always enabled.
*
*
* Methods of this class will be invoked on a background thread and care must be taken to
* correctly synchronize access to any shared state.
*
* On Android KitKat and above these methods may be called on more than one thread. This thread
* may be different than the thread on which the shouldInterceptRequest method was invoked.
* This means that on Android KitKat and above it is possible to block in this method without
* blocking other resources from loading. The number of threads used to parallelize loading
* is an internal implementation detail of the WebView and may change between updates which
* means that the amount of time spent blocking in this method should be kept to an absolute
* minimum.
*/
@VisibleForTesting
/*package*/ static class PathMatcher {
static final String HTTP_SCHEME = "http";
static final String HTTPS_SCHEME = "https";
final boolean mHttpEnabled;
@NonNull final String mAuthority;
@NonNull final String mPath;
@NonNull final PathHandler mHandler;
/**
* @param authority the authority to match (For instance {@code "example.com"})
* @param path the prefix path to match, it should start and end with a {@code "/"}.
* @param httpEnabled enable hosting under the HTTP scheme, HTTPS is always enabled.
* @param handler the {@link PathHandler} the handler class for this URI.
*/
PathMatcher(@NonNull final String authority, @NonNull final String path,
boolean httpEnabled, @NonNull final PathHandler handler) {
if (path.isEmpty() || path.charAt(0) != '/') {
throw new IllegalArgumentException("Path should start with a slash '/'.");
}
if (!path.endsWith("/")) {
throw new IllegalArgumentException("Path should end with a slash '/'");
}
mAuthority = authority;
mPath = path;
mHttpEnabled = httpEnabled;
mHandler = handler;
}
/**
* Match against registered scheme, authority and path prefix.
*
* Match happens when:
*
* The path should start and end with a {@code "/"} and it shouldn't collide with a real web
* path.
*
* {@code WebViewAssetLoader} will try {@code PathHandlers} in the order they're
* registered, and will use whichever is the first to return a non-{@code null} {@link
* WebResourceResponse}.
*
* @param path the prefix path where this handler should be register.
* @param handler {@link PathHandler} that handles requests for this path.
* @return {@link Builder} object.
* @throws IllegalArgumentException if the path is invalid.
*/
@NonNull
public Builder addPathHandler(@NonNull String path, @NonNull PathHandler handler) {
mHandlerList.add(Pair.create(path, handler));
return this;
}
/**
* Build and return a {@link WebViewAssetLoader} object.
*
* @return immutable {@link WebViewAssetLoader} object.
*/
@NonNull
public WebViewAssetLoader build() {
List
* This method should be invoked from within
* {@link android.webkit.WebViewClient#shouldInterceptRequest(android.webkit.WebView, String)}.
*
* @param url the URL to process.
* @return {@link WebResourceResponse} if the request URL matches a registered URL,
* {@code null} otherwise.
*/
@WorkerThread
@Nullable
public WebResourceResponse shouldInterceptRequest(@NonNull Uri url) {
for (PathMatcher matcher : mMatchers) {
PathHandler handler = matcher.match(url);
// The requested URL doesn't match the URL where this handler has been registered.
if (handler == null) continue;
String suffixPath = matcher.getSuffixPath(url.getPath());
WebResourceResponse response = handler.handle(suffixPath);
// Handler doesn't want to intercept this request, try next handler.
if (response == null) continue;
return response;
}
return null;
}
}
* File publicDir = new File(context.getFilesDir(), "public");
* // Host "files/public/" in app's data directory under:
* // http://appassets.androidplatform.net/public/...
* WebViewAssetLoader assetLoader = new WebViewAssetLoader.Builder()
* .addPathHandler("/public/", new InternalStoragePathHandler(context, publicDir))
* .build();
*
*/
public static final class InternalStoragePathHandler implements PathHandler {
/**
* Forbidden subdirectories of {@link Context#getDataDir} that cannot be exposed by this
* handler. They are forbidden as they often contain sensitive information.
*
*
*
* @param uri the URI whose path we will match against.
*
* @return {@code PathHandler} if a match happens, {@code null} otherwise.
*/
@WorkerThread
@Nullable
public PathHandler match(@NonNull Uri uri) {
// Only match HTTP_SCHEME if caller enabled HTTP matches.
if (uri.getScheme().equals(HTTP_SCHEME) && !mHttpEnabled) {
return null;
}
// Don't match non-HTTP(S) schemes.
if (!uri.getScheme().equals(HTTP_SCHEME) && !uri.getScheme().equals(HTTPS_SCHEME)) {
return null;
}
if (!uri.getAuthority().equals(mAuthority)) {
return null;
}
if (!uri.getPath().startsWith(mPath)) {
return null;
}
return mHandler;
}
/**
* Utility method to get the suffix path of a matched path.
*
* @param path the full received path.
* @return the suffix path.
*/
@WorkerThread
@NonNull
public String getSuffixPath(@NonNull String path) {
return path.replaceFirst(mPath, "");
}
}
/**
* A builder class for constructing {@link WebViewAssetLoader} objects.
*/
public static final class Builder {
private boolean mHttpAllowed;
private String mDomain = DEFAULT_DOMAIN;
// This is stored as a List