WebViewCompat

public class WebViewCompat

Compatibility version of android.webkit.WebView

Summary

Nested types
@Retention(value = RetentionPolicy.CLASS)
@Target(value = [ElementType.METHOD, ElementType.TYPE, ElementType.FIELD])
@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
public annotation WebViewCompat.ExperimentalAsyncStartUp

Denotes that the startUpWebView API surface is experimental.
@Retention(value = RetentionPolicy.CLASS)
@Target(value = [ElementType.METHOD, ElementType.TYPE, ElementType.FIELD])
@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
public annotation WebViewCompat.ExperimentalCacheProvider

Denotes that the WebViewCompat#setShouldCacheProvider API surface is experimental.
@Retention(value = RetentionPolicy.CLASS)
@Target(value = [ElementType.METHOD, ElementType.TYPE, ElementType.FIELD])
@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
public annotation WebViewCompat.ExperimentalSaveState

Denotes that the WebViewCompat#saveState API surface is experimental.
@Retention(value = RetentionPolicy.CLASS)
@Target(value = [ElementType.METHOD, ElementType.TYPE, ElementType.FIELD])
@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
public annotation WebViewCompat.ExperimentalUrlPrerender

Denotes that the PrerenderUrl API surface is experimental.

Callback interface supplied to postVisualStateCallback for receiving notifications about the visual state.

This listener receives messages sent on the JavaScript object which was injected by addWebMessageListener.

Callback interface for startUpWebView.

Public methods
static @NonNull ScriptHandler
@UiThread
@RequiresFeature(name = WebViewFeature.DOCUMENT_START_SCRIPT, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
addDocumentStartJavaScript(
    @NonNull WebView webview,
    @NonNull String script,
    @NonNull Set<String> allowedOriginRules
)

Adds a JavaScript script to the WebView which will be executed in any frame whose origin matches allowedOriginRules when the document begins to load.
static void
@UiThread
@RequiresFeature(name = WebViewFeature.WEB_MESSAGE_LISTENER, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
addWebMessageListener(
    @NonNull WebView webView,
    @NonNull String jsObjectName,
    @NonNull Set<String> allowedOriginRules,
    @NonNull WebViewCompat.WebMessageListener listener
)

Adds a WebMessageListener to the WebView and injects a JavaScript object into each frame that the WebMessageListener will listen on.
static @NonNull WebMessagePortCompat[]
@UiThread
@RequiresFeature(name = WebViewFeature.CREATE_WEB_MESSAGE_CHANNEL, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
createWebMessageChannel(@NonNull WebView webview)

Creates a message channel to communicate with JS and returns the message ports that represent the endpoints of this message channel.
static @Nullable PackageInfo

If WebView has already been loaded into the current process this method will return the package that was used to load it.
static @NonNull Profile
@UiThread
@RequiresFeature(name = WebViewFeature.MULTI_PROFILE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
getProfile(@NonNull WebView webView)

Gets the Profile associated with this WebView.
static @NonNull Uri
@AnyThread
@RequiresFeature(name = WebViewFeature.SAFE_BROWSING_PRIVACY_POLICY_URL, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
getSafeBrowsingPrivacyPolicyUrl()

Returns a URL pointing to the privacy policy for Safe Browsing reporting.
static @NonNull String
@AnyThread
@RequiresFeature(name = WebViewFeature.GET_VARIATIONS_HEADER, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
getVariationsHeader()

Gets the WebView variations encoded to be used as the X-Client-Data HTTP header.
static @Nullable WebChromeClient
@UiThread
@RequiresFeature(name = WebViewFeature.GET_WEB_CHROME_CLIENT, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
getWebChromeClient(@NonNull WebView webview)

Gets the WebChromeClient.
static @NonNull WebNavigationClient
@RequiresFeature(name = WebViewFeature.NAVIGATION_CALLBACK_BASIC, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@WebNavigationClient.ExperimentalNavigationCallback
getWebNavigationClient(@NonNull WebView webView)

Gets the WebNavigationClient currently set for the given WebView.
static @NonNull WebViewClient
@UiThread
@RequiresFeature(name = WebViewFeature.GET_WEB_VIEW_CLIENT, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
getWebViewClient(@NonNull WebView webview)

Gets the WebViewClient for the WebView argument.
static @Nullable WebViewRenderProcess
@UiThread
@RequiresFeature(name = WebViewFeature.GET_WEB_VIEW_RENDERER, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
getWebViewRenderProcess(@NonNull WebView webview)

Gets the WebView renderer associated with this WebView.
static @Nullable WebViewRenderProcessClient
@UiThread
@RequiresFeature(name = WebViewFeature.WEB_VIEW_RENDERER_CLIENT_BASIC_USAGE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
getWebViewRenderProcessClient(@NonNull WebView webview)

Gets the renderer client object associated with this WebView.
static boolean
@UiThread
@RequiresFeature(name = WebViewFeature.MUTE_AUDIO, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
isAudioMuted(@NonNull WebView webView)

Returns whether this WebView is muted.
static boolean
@AnyThread
@RequiresFeature(name = WebViewFeature.MULTI_PROCESS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
isMultiProcessEnabled()

Returns true if WebView is running in multi process mode.
static void
@UiThread
@RequiresFeature(name = WebViewFeature.VISUAL_STATE_CALLBACK, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
postVisualStateCallback(
    @NonNull WebView webview,
    long requestId,
    @NonNull WebViewCompat.VisualStateCallback callback
)

Posts a VisualStateCallback, which will be called when the current state of the WebView is ready to be drawn.
static void
@UiThread
@RequiresFeature(name = WebViewFeature.POST_WEB_MESSAGE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
postWebMessage(
    @NonNull WebView webview,
    @NonNull WebMessageCompat message,
    @NonNull Uri targetOrigin
)

Post a message to main frame.
static void
@RequiresFeature(name = WebViewFeature.PRERENDER_WITH_URL, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@WebViewCompat.ExperimentalUrlPrerender
prerenderUrlAsync(
    @NonNull WebView webView,
    @NonNull String url,
    @Nullable CancellationSignal cancellationSignal,
    @NonNull Executor callbackExecutor,
    @NonNull PrerenderOperationCallback callback
)

Starts a URL prerender request for this WebView.
static void
@RequiresFeature(name = WebViewFeature.PRERENDER_WITH_URL, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@WebViewCompat.ExperimentalUrlPrerender
prerenderUrlAsync(
    @NonNull WebView webView,
    @NonNull String url,
    @Nullable CancellationSignal cancellationSignal,
    @NonNull Executor callbackExecutor,
    @NonNull SpeculativeLoadingParameters params,
    @NonNull PrerenderOperationCallback callback
)

The same as prerenderUrlAsync, but allows customizing the request by providing SpeculativeLoadingParameters.
static void
@UiThread
@RequiresFeature(name = WebViewFeature.WEB_MESSAGE_LISTENER, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
removeWebMessageListener(
    @NonNull WebView webview,
    @NonNull String jsObjectName
)

Removes the WebMessageListener associated with jsObjectName.
static void
@RequiresFeature(name = WebViewFeature.SAVE_STATE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@WebViewCompat.ExperimentalSaveState
saveState(
    @NonNull WebView webView,
    @NonNull Bundle outState,
    @IntRange(from = 1) int maxSizeBytes,
    boolean includeForwardState
)

Saves the state of the provided WebView, such as for use with onSaveInstanceState.
static void
@UiThread
@RequiresFeature(name = WebViewFeature.MUTE_AUDIO, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
setAudioMuted(@NonNull WebView webView, boolean mute)

Mute or un-mute this WebView.
static void
@AnyThread
@RequiresFeature(name = WebViewFeature.DEFAULT_TRAFFICSTATS_TAGGING, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
setDefaultTrafficStatsTag(int tag)

Sets the default android.net.TrafficStats tag to use when accounting socket traffic caused by WebView.
static void
@UiThread
@RequiresFeature(name = WebViewFeature.MULTI_PROFILE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
setProfile(@NonNull WebView webView, @NonNull String profileName)

Sets the Profile with its name as the current Profile for this WebView.
static void
@AnyThread
@RequiresFeature(name = WebViewFeature.SAFE_BROWSING_ALLOWLIST, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
setSafeBrowsingAllowlist(
    @NonNull Set<String> hosts,
    @Nullable ValueCallback<Boolean> callback
)

Configures a set of hosts (domain names/IP addresses) that are exempt from SafeBrowsing checks.
static void
@AnyThread
@RequiresFeature(name = WebViewFeature.SAFE_BROWSING_WHITELIST, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
setSafeBrowsingWhitelist(
    @NonNull List<String> hosts,
    @Nullable ValueCallback<Boolean> callback
)

This method is deprecated.

Please use setSafeBrowsingAllowlist instead.
static void
@RequiresFeature(name = WebViewFeature.CACHE_PROVIDER, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@AnyThread
@WebViewCompat.ExperimentalCacheProvider
setShouldCacheProvider(boolean shouldCacheProvider)

Enables or disables caching of WebView provider objects (objects internal to the androidx.webkit library).
static void
@RequiresFeature(name = WebViewFeature.NAVIGATION_CALLBACK_BASIC, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@WebNavigationClient.ExperimentalNavigationCallback
setWebNavigationClient(
    @NonNull WebView webView,
    @NonNull WebNavigationClient client
)

Sets the WebNavigationClient for the given WebView.
static void
@UiThread
@RequiresFeature(name = WebViewFeature.WEB_VIEW_RENDERER_CLIENT_BASIC_USAGE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
setWebViewRenderProcessClient(
    @NonNull WebView webview,
    @Nullable WebViewRenderProcessClient webViewRenderProcessClient
)

Sets the renderer client object associated with this WebView.
static void
@UiThread
@RequiresFeature(name = WebViewFeature.WEB_VIEW_RENDERER_CLIENT_BASIC_USAGE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
setWebViewRenderProcessClient(
    @NonNull WebView webview,
    @NonNull Executor executor,
    @NonNull WebViewRenderProcessClient webViewRenderProcessClient
)

Sets the renderer client object associated with this WebView.
static void
@AnyThread
@RequiresFeature(name = WebViewFeature.START_SAFE_BROWSING, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
startSafeBrowsing(
    @NonNull Context context,
    @Nullable ValueCallback<Boolean> callback
)

This method is deprecated.

In WebView version 122.0.6174.0 and later, this initialization is done automatically, so there is no need to call this API.
static void

Asynchronously trigger WebView startup.

Public methods

addDocumentStartJavaScript

Added in 1.9.0
@UiThread
@RequiresFeature(name = WebViewFeature.DOCUMENT_START_SCRIPT, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
public static @NonNull ScriptHandler addDocumentStartJavaScript(
    @NonNull WebView webview,
    @NonNull String script,
    @NonNull Set<String> allowedOriginRules
)

Adds a JavaScript script to the WebView which will be executed in any frame whose origin matches allowedOriginRules when the document begins to load.

Note that the script will run before any of the page's JavaScript code and the DOM tree might not be ready at this moment. It will block the loading of the page until it's finished, so should be kept as short as possible.

The injected object from addWebMessageListener API will be injected first and the script can rely on the injected object to send messages to the app.

The script will only run in frames which begin loading after the call returns, therefore it should typically be called before making any loadUrl(), loadData() or loadDataWithBaseURL() call to load the page.

This method can be called multiple times to inject multiple scripts. If more than one script matches a frame's origin, they will be executed in the order they were added.

See addWebMessageListener for the rules of the allowedOriginRules parameter.

This method should only be called if isFeatureSupported returns true for DOCUMENT_START_SCRIPT.

Parameters
@NonNull WebView webview

The WebView instance that we are interacting with.
@NonNull String script

The JavaScript script to be executed.
@NonNull Set<String> allowedOriginRules

A set of matching rules for the allowed origins.
Returns
@NonNull ScriptHandler

the ScriptHandler, which is a handle for removing the script.
Throws
java.lang.IllegalArgumentException

If one of the allowedOriginRules is invalid.
See also
addWebMessageListener
ScriptHandler

addWebMessageListener

Added in 1.3.0
@UiThread
@RequiresFeature(name = WebViewFeature.WEB_MESSAGE_LISTENER, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
public static void addWebMessageListener(
    @NonNull WebView webView,
    @NonNull String jsObjectName,
    @NonNull Set<String> allowedOriginRules,
    @NonNull WebViewCompat.WebMessageListener listener
)

Adds a WebMessageListener to the WebView and injects a JavaScript object into each frame that the WebMessageListener will listen on.

The injected JavaScript object will be named jsObjectName in the global scope. This will inject the JavaScript object in any frame whose origin matches allowedOriginRules for every navigation after this call, and the JavaScript object will be available immediately when the page begins to load.

Each allowedOriginRules entry must follow the format SCHEME "://" [ HOSTNAME_PATTERN [ ":" PORT ] ], each part is explained in the below table:

Rule Description Example
http/https with hostname SCHEME is http or https; HOSTNAME_PATTERN is a regular hostname; PORT is optional, when not present, the rule will match port 80 for http and port 443 for https.
  • https://foobar.com:8080 - Matches https:// URL on port 8080, whose normalized host is foobar.com.
  • https://www.example.com - Matches https:// URL on port 443, whose normalized host is www.example.com.
http/https with pattern matching SCHEME is http or https; HOSTNAME_PATTERN is a sub-domain matching pattern with a leading *.; PORT is optional, when not present, the rule will match port 80 for http and port 443 for https.
  • https://*.example.com - Matches https://calendar.example.com and https://foo.bar.example.com but not https://example.com.
  • https://*.example.com:8080 - Matches https://calendar.example.com:8080
http/https with IP literal SCHEME is https or https; HOSTNAME_PATTERN is IP literal; PORT is optional, when not present, the rule will match port 80 for http and port 443 for https.
  • https://127.0.0.1 - Matches https:// URL on port 443, whose IPv4 address is 127.0.0.1
  • https://[::1] or https://[0:0::1]- Matches any URL to the IPv6 loopback address with port 443.
  • https://[::1]:99 - Matches any https:// URL to the IPv6 loopback on port 99.
Custom scheme SCHEME is a custom scheme; HOSTNAME_PATTERN and PORT must not be present.
  • my-app-scheme:// - Matches any my-app-scheme:// URL.
* Wildcard rule, matches any origin.
  • *

Note that this is a powerful API, as the JavaScript object will be injected when the frame's origin matches any one of the allowed origins. The HTTPS scheme is strongly recommended for security; allowing HTTP origins exposes the injected object to any potential network-based attackers. If a wildcard "*" is provided, it will inject the JavaScript object to all frames. A wildcard should only be used if the app wants any third party web page to be able to use the injected object. When using a wildcard, the app must treat received messages as untrustworthy and validate any data carefully.

This method can be called multiple times to inject multiple JavaScript objects.

Let's say the injected JavaScript object is named myObject. We will have following methods on that object once it is available to use: 

// Web page (in JavaScript)
// message needs to be a JavaScript String or ArrayBuffer, MessagePorts is an optional
// parameter.
myObject.postMessage(message[, MessagePorts])

          

// To receive messages posted from the app side, assign a function to the "onmessage"
// property. This function should accept a single "event" argument. "event" has a "data"
// property, which is the message String or ArrayBuffer from the app side.
myObject.onmessage = function(event) { ... }


          

// To be compatible with DOM EventTarget's addEventListener, it accepts type and listener
// parameters, where type can be only "message" type and listener can only be a JavaScript
// function for myObject. An event object will be passed to listener with a "data" property,
// which is the message String or ArrayBuffer from the app side.
myObject.addEventListener(type, listener)


          

// To be compatible with DOM EventTarget's removeEventListener, it accepts type and listener
// parameters, where type can be only "message" type and listener can only be a JavaScript
// function for myObject.
myObject.removeEventListener(type, listener)

We start the communication between JavaScript and the app from the JavaScript side. In order to send message from the app to JavaScript, it needs to post a message from JavaScript first, so the app will have a JavaScriptReplyProxy object to respond. Example: 

// Web page (in JavaScript)
myObject.onmessage = function(event) {
  // prints "Got it!" when we receive the app's response.
  console.log(event.data);
}
myObject.postMessage("I'm ready!");
 
// App (in Java)
WebMessageListener myListener = new WebMessageListener() {
  @Override
  public void onPostMessage(WebView view, WebMessageCompat message, Uri sourceOrigin,
           boolean isMainFrame, JavaScriptReplyProxy replyProxy) {
    // do something about view, message, sourceOrigin and isMainFrame.
    replyProxy.postMessage("Got it!");
  }
};
if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_MESSAGE_LISTENER)) {
  WebViewCompat.addWebMessageListener(webView, "myObject", rules, myListener);
}

Suppose the communication is already setup, to send ArrayBuffer from the app to web, it needs to check feature flag(WEB_MESSAGE_ARRAY_BUFFER). Here is a example to send file content from app to web: 

// App (in Java)
WebMessageListener myListener = new WebMessageListener() {
  @Override
  public void onPostMessage(WebView view, WebMessageCompat message, Uri sourceOrigin,
           boolean isMainFrame, JavaScriptReplyProxy replyProxy) {
    // Communication is setup, send file data to web.
    if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_MESSAGE_ARRAY_BUFFER)) {
      // Suppose readFileData method is to read content from file.
      byte[] fileData = readFileData("myFile.dat");
      replyProxy.postMessage(fileData);
    }
  }
}
 
// Web page (in JavaScript)
myObject.onmessage = function(event) {
  if (event.data instanceof ArrayBuffer) {
    const data = event.data;  // Received file content from app.
    const dataView = new DataView(data);
    // Consume file content by using JavaScript DataView to access ArrayBuffer.
  }
}
myObject.postMessage("Setup!");

Suppose the communication is already setup, and feature flag WEB_MESSAGE_ARRAY_BUFFER is check. Here is a example to download image in WebView, and send to app: 

// Web page (in JavaScript)
const response = await fetch('example.jpg');
if (response.ok) {
    const imageData = await response.arrayBuffer();
    myObject.postMessage(imageData);
}
 
// App (in Java)
WebMessageListener myListener = new WebMessageListener() {
  @Override
  public void onPostMessage(WebView view, WebMessageCompat message, Uri sourceOrigin,
           boolean isMainFrame, JavaScriptReplyProxy replyProxy) {
    if (message.getType() == WebMessageCompat.TYPE_ARRAY_BUFFER) {
      byte[] imageData = message.getArrayBuffer();
      // do something like draw image on ImageView.
    }
  }
};

This method should only be called if isFeatureSupported returns true for WEB_MESSAGE_LISTENER.

Parameters
@NonNull WebView webView

The WebView instance that we are interacting with.
@NonNull String jsObjectName

The name for the injected JavaScript object for this .
@NonNull Set<String> allowedOriginRules

A set of matching rules for the allowed origins.
@NonNull WebViewCompat.WebMessageListener listener

The WebMessageListener to handle postMessage() calls on the JavaScript object.
Throws
java.lang.IllegalArgumentException

If one of the allowedOriginRules is invalid.
See also
JavaScriptReplyProxy
WebViewCompat.WebMessageListener

createWebMessageChannel

Added in 1.1.0
@UiThread
@RequiresFeature(name = WebViewFeature.CREATE_WEB_MESSAGE_CHANNEL, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
public static @NonNull WebMessagePortCompat[] createWebMessageChannel(@NonNull WebView webview)

Creates a message channel to communicate with JS and returns the message ports that represent the endpoints of this message channel. The HTML5 message channel functionality is described here

The returned message channels are entangled and already in started state.

This method should only be called if isFeatureSupported returns true for CREATE_WEB_MESSAGE_CHANNEL.

Returns
@NonNull WebMessagePortCompat[]

an array of size two, containing the two message ports that form the message channel.

getCurrentWebViewPackage

Added in 1.1.0
@AnyThread
public static @Nullable PackageInfo getCurrentWebViewPackage(@NonNull Context context)

If WebView has already been loaded into the current process this method will return the package that was used to load it. Otherwise, the package that would be used if the WebView was loaded right now will be returned; this does not cause WebView to be loaded, so this information may become outdated at any time. The WebView package changes either when the current WebView package is updated, disabled, or uninstalled. It can also be changed through a Developer Setting. If the WebView package changes, any app process that has loaded WebView will be killed. The next time the app starts and loads WebView it will use the new WebView package instead.

Returns
@Nullable PackageInfo

the current WebView package, or null if there is none.

getProfile

Added in 1.9.0
@UiThread
@RequiresFeature(name = WebViewFeature.MULTI_PROFILE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
public static @NonNull Profile getProfile(@NonNull WebView webView)

Gets the Profile associated with this WebView.

Gets the profile object set on this WebView using setProfile, or the default profile if it has not been changed.

Parameters
@NonNull WebView webView

the WebView to get the profile object associated with.
Returns
@NonNull Profile

the profile object set to this WebView.
Throws
java.lang.IllegalStateException

if the WebView has been destroyed.

getSafeBrowsingPrivacyPolicyUrl

Added in 1.1.0
@AnyThread
@RequiresFeature(name = WebViewFeature.SAFE_BROWSING_PRIVACY_POLICY_URL, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
public static @NonNull Uri getSafeBrowsingPrivacyPolicyUrl()

Returns a URL pointing to the privacy policy for Safe Browsing reporting.

This method should only be called if isFeatureSupported returns true for SAFE_BROWSING_PRIVACY_POLICY_URL.

Returns
@NonNull Uri

the url pointing to a privacy policy document which can be displayed to users.

getVariationsHeader

Added in 1.5.0
@AnyThread
@RequiresFeature(name = WebViewFeature.GET_VARIATIONS_HEADER, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
public static @NonNull String getVariationsHeader()

Gets t