WebViewCompat

Kotlin |Java

open class WebViewCompat

kotlin.Any
↳	androidx.webkit.WebViewCompat

Compatibility version of android.webkit.WebView

Summary

Nested classes
abstract	VisualStateCallback Callback interface supplied to postVisualStateCallback for receiving notifications about the visual state.
abstract	WebMessageListener This listener receives messages sent on the JavaScript object which was injected by .

Public methods
open static Unit	addWebMessageListener(@NonNull webView: WebView, @NonNull jsObjectName: String, @NonNull allowedOriginRules: MutableSet<String!>, @NonNull listener: WebViewCompat.WebMessageListener) Adds a WebMessageListener to the WebView and injects a JavaScript object into each frame that the WebMessageListener will listen on.
open static Array<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.
open static 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.
open static Uri	getSafeBrowsingPrivacyPolicyUrl() Returns a URL pointing to the privacy policy for Safe Browsing reporting.
open static WebChromeClient?	getWebChromeClient(@NonNull webview: WebView) Gets the WebChromeClient.
open static WebViewClient	getWebViewClient(@NonNull webview: WebView) Gets the WebViewClient for the WebView argument.
open static WebViewRenderProcess?	getWebViewRenderProcess(@NonNull webview: WebView) Gets the WebView renderer associated with this WebView.
open static WebViewRenderProcessClient?	getWebViewRenderProcessClient(@NonNull webview: WebView) Gets the renderer client object associated with this WebView.
open static Boolean	isMultiProcessEnabled() Returns true if WebView is running in multi process mode.
open static Unit	postVisualStateCallback(@NonNull webview: WebView, requestId: Long, @NonNull callback: WebViewCompat.VisualStateCallback) Posts a VisualStateCallback, which will be called when the current state of the WebView is ready to be drawn.
open static Unit	postWebMessage(@NonNull webview: WebView, @NonNull message: WebMessageCompat, @NonNull targetOrigin: Uri) Post a message to main frame.
open static Unit	removeWebMessageListener(@NonNull webview: WebView, @NonNull jsObjectName: String) Removes the WebMessageListener associated with jsObjectName.
open static Unit	setSafeBrowsingWhitelist(@NonNull hosts: MutableList<String!>, @Nullable callback: ValueCallback<Boolean!>?) Sets the list of hosts (domain names/IP addresses) that are exempt from SafeBrowsing checks.
open static Unit	setWebViewRenderProcessClient(@NonNull webview: WebView, @NonNull executor: Executor, @NonNull webViewRenderProcessClient: WebViewRenderProcessClient) Sets the renderer client object associated with this WebView.
open static Unit	setWebViewRenderProcessClient(@NonNull webview: WebView, @Nullable webViewRenderProcessClient: WebViewRenderProcessClient?) Sets the renderer client object associated with this WebView.
open static Unit	startSafeBrowsing(@NonNull context: Context, @Nullable callback: ValueCallback<Boolean!>?) Starts Safe Browsing initialization.

Public methods

addWebMessageListener

open static fun addWebMessageListener(
    @NonNull webView: WebView, 
    @NonNull jsObjectName: String, 
    @NonNull allowedOriginRules: MutableSet<String!>, 
    @NonNull listener: WebViewCompat.WebMessageListener
): Unit

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:

// message needs to be a JavaScript String, MessagePorts is an optional parameter.
      myObject.postMessage(message[, MessagePorts])
     
      // To receive the message posted from the app side. event has a "data" property, which is the
      // message string from the app side.
      myObject.onmessage(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 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!");
        }
      };
      WebViewCompat.addWebMessageListener(webView, "myObject", rules, myListener);
      

This method should only be called if WebViewFeature#isFeatureSupported(String) returns true for WebViewFeature#WEB_MESSAGE_LISTENER.

Parameters
webView	WebView: The WebView instance that we are interacting with.
jsObjectName	String: The name for the injected JavaScript object for this .
allowedOriginRules	MutableSet<String!>: A set of matching rules for the allowed origins.
listener	WebViewCompat.WebMessageListener: The WebMessageListener to handle postMessage() calls on the JavaScript object.

Exceptions
IllegalArgumentException	If one of the allowedOriginRules is invalid.

See Also

• JavaScriptReplyProxy
• WebMessageListener

createWebMessageChannel

@NonNull open static fun createWebMessageChannel(@NonNull webview: WebView): Array<WebMessagePortCompat!>

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 WebViewFeature#isFeatureSupported(String) returns true for WebViewFeature#CREATE_WEB_MESSAGE_CHANNEL.

Return
Array<WebMessagePortCompat!>	an array of size two, containing the two message ports that form the message channel.

getCurrentWebViewPackage

@Nullable open static fun getCurrentWebViewPackage(@NonNull context: Context): PackageInfo?

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.

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

getSafeBrowsingPrivacyPolicyUrl

@NonNull open static fun getSafeBrowsingPrivacyPolicyUrl(): Uri

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

This method should only be called if WebViewFeature#isFeatureSupported(String) returns true for WebViewFeature#SAFE_BROWSING_PRIVACY_POLICY_URL.

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

getWebChromeClient

@Nullable open static fun getWebChromeClient(@NonNull webview: WebView): WebChromeClient?

Gets the WebChromeClient.

This method should only be called if WebViewFeature#isFeatureSupported(String) returns true for WebViewFeature#GET_WEB_CHROME_CLIENT.

Return
WebChromeClient?	the WebChromeClient, or null if not yet set

getWebViewClient

@NonNull open static fun getWebViewClient(@NonNull webview: WebView): WebViewClient

Gets the WebViewClient for the WebView argument.

This method should only be called if WebViewFeature#isFeatureSupported(String) returns true for WebViewFeature#GET_WEB_VIEW_CLIENT.

Return
WebViewClient	the WebViewClient, or a default client if not yet set

getWebViewRenderProcess

@Nullable open static fun getWebViewRenderProcess(@NonNull webview: WebView): WebViewRenderProcess?

Gets the WebView renderer associated with this WebView.

In Android O and above, WebView may run in "multiprocess" mode. In multiprocess mode, rendering of web content is performed by a sandboxed renderer process separate to the application process. This renderer process may be shared with other WebViews in the application, but is not shared with other application processes.

If WebView is running in multiprocess mode, this method returns a handle to the renderer process associated with the WebView, which can be used to control the renderer process.

This method should only be called if WebViewFeature#isFeatureSupported(String) returns true for WebViewFeature#GET_WEB_VIEW_RENDERER.

Return
WebViewRenderProcess?	the WebViewRenderProcess renderer handle associated with this android.webkit.WebView, or null if WebView is not runing in multiprocess mode.

getWebViewRenderProcessClient

@Nullable open static fun getWebViewRenderProcessClient(@NonNull webview: WebView): WebViewRenderProcessClient?

Gets the renderer client object associated with this WebView.

This method should only be called if WebViewFeature#isFeatureSupported(String) returns true for WebViewFeature#WEB_VIEW_RENDERER_CLIENT_BASIC_USAGE.

Return
WebViewRenderProcessClient?	the WebViewRenderProcessClient object associated with this WebView, if one has been set via setWebViewRenderProcessClient(WebView,WebViewRenderProcessClient) or null otherwise.

isMultiProcessEnabled

open static fun isMultiProcessEnabled(): Boolean

Returns true if WebView is running in multi process mode.

In Android O and above, WebView may run in "multiprocess" mode. In multiprocess mode, rendering of web content is performed by a sandboxed renderer process separate to the application process. This renderer process may be shared with other WebViews in the application, but is not shared with other application processes.

postVisualStateCallback

open static fun postVisualStateCallback(
    @NonNull webview: WebView, 
    requestId: Long, 
    @NonNull callback: WebViewCompat.VisualStateCallback
): Unit

Posts a VisualStateCallback, which will be called when the current state of the WebView is ready to be drawn.

Because updates to the DOM are processed asynchronously, updates to the DOM may not immediately be reflected visually by subsequent WebView#onDraw invocations. The VisualStateCallback provides a mechanism to notify the caller when the contents of the DOM at the current time are ready to be drawn the next time the WebView draws.

The next draw after the callback completes is guaranteed to reflect all the updates to the DOM up to the point at which the VisualStateCallback was posted, but it may also contain updates applied after the callback was posted.

The state of the DOM covered by this API includes the following:

• primitive HTML elements (div, img, span, etc..)
• images
• CSS animations
• WebGL
• canvas

It does not include the state of:

• the video tag

To guarantee that the WebView will successfully render the first frame after the VisualStateCallback#onComplete method has been called a set of conditions must be met:

• If the WebView's visibility is set to VISIBLE then * the WebView must be attached to the view hierarchy.
• If the WebView's visibility is set to INVISIBLE then the WebView must be attached to the view hierarchy and must be made VISIBLE from the VisualStateCallback#onComplete method.
• If the WebView's visibility is set to GONE then the WebView must be attached to the view hierarchy and its LayoutParams's width and height need to be set to fixed values and must be made VISIBLE from the VisualStateCallback#onComplete method.

When using this API it is also recommended to enable pre-rasterization if the is off screen to avoid flickering. See android.webkit.WebSettings#setOffscreenPreRaster for more details and do consider its caveats.

This method should only be called if WebViewFeature#isFeatureSupported(String) returns true for WebViewFeature#VISUAL_STATE_CALLBACK.

Parameters
requestId	Long: An id that will be returned in the callback to allow callers to match requests with callbacks.
callback	WebViewCompat.VisualStateCallback: The callback to be invoked.

postWebMessage

open static fun postWebMessage(
    @NonNull webview: WebView, 
    @NonNull message: WebMessageCompat, 
    @NonNull targetOrigin: Uri
): Unit

Post a message to main frame. The embedded application can restrict the messages to a certain target origin. See HTML5 spec for how target origin can be used.

A target origin can be set as a wildcard ("*"). However this is not recommended. See the page above for security issues.

This method should only be called if WebViewFeature#isFeatureSupported(String) returns true for WebViewFeature#POST_WEB_MESSAGE.

Parameters
message	WebMessageCompat: the WebMessage
targetOrigin	Uri: the target origin.

removeWebMessageListener

open static fun removeWebMessageListener(
    @NonNull webview: WebView, 
    @NonNull jsObjectName: String
): Unit

Removes the WebMessageListener associated with jsObjectName.

Note that after this call, the injected JavaScript object is still in the JavaScript context, however any message sent after this call won't reach the WebMessageListener.

This method should only be called if WebViewFeature#isFeatureSupported(String) returns true for WebViewFeature#WEB_MESSAGE_LISTENER.

Parameters
jsObjectName	String: The JavaScript object's name that was previously passed to .

See Also

• #addWebMessageListener(WebView, String, Set, WebMessageListener)

setSafeBrowsingWhitelist

open static fun setSafeBrowsingWhitelist(
    @NonNull hosts: MutableList<String!>, 
    @Nullable callback: ValueCallback<Boolean!>?
): Unit

Sets the list of hosts (domain names/IP addresses) that are exempt from SafeBrowsing checks. The list is global for all the WebViews.

Each rule should take one of these:

Rule	Example	Matches Subdomain
HOSTNAME	example.com	Yes
.HOSTNAME	.example.com	No
IPV4_LITERAL	192.168.1.1	No
IPV6_LITERAL_WITH_BRACKETS	[10:20:30:40:50:60:70:80]	No

All other rules, including wildcards, are invalid.

The correct syntax for hosts is defined by RFC 3986.

This method should only be called if WebViewFeature#isFeatureSupported(String) returns true for WebViewFeature#SAFE_BROWSING_WHITELIST.

Parameters
hosts	MutableList<String!>: the list of hosts
callback	ValueCallback<Boolean!>?: will be called with true if hosts are successfully added to the whitelist. It will be called with false if any hosts are malformed. The callback will be run on the UI thread

setWebViewRenderProcessClient

open static fun setWebViewRenderProcessClient(
    @NonNull webview: WebView, 
    @NonNull executor: Executor, 
    @NonNull webViewRenderProcessClient: WebViewRenderProcessClient
): Unit

Sets the renderer client object associated with this WebView.

The renderer client encapsulates callbacks relevant to WebView renderer state. See WebViewRenderProcessClient for details.

Although many WebView instances may share a single underlying renderer, and renderers may live either in the application process, or in a sandboxed process that is isolated from the application process, instances of WebViewRenderProcessClient are set per-WebView. Callbacks represent renderer events from the perspective of this WebView, and may or may not be correlated with renderer events affecting other WebViews.

The renderer client encapsulates callbacks relevant to WebView renderer state. See WebViewRenderProcessClient for details.

Although many WebView instances may share a single underlying renderer, and renderers may live either in the application process, or in a sandboxed process that is isolated from the application process, instances of WebViewRenderProcessClient are set per-WebView. Callbacks represent renderer events from the perspective of this WebView, and may or may not be correlated with renderer events affecting other WebViews.

This method should only be called if WebViewFeature#isFeatureSupported(String) returns true for WebViewFeature#WEB_VIEW_RENDERER_CLIENT_BASIC_USAGE.

Parameters
webview	WebView: the WebView on which to monitor responsiveness.
executor	Executor: the Executor that will be used to execute callbacks.
webViewRenderProcessClient	WebViewRenderProcessClient: the WebViewRenderProcessClient to set for callbacks.

setWebViewRenderProcessClient

open static fun setWebViewRenderProcessClient(
    @NonNull webview: WebView, 
    @Nullable webViewRenderProcessClient: WebViewRenderProcessClient?
): Unit

Sets the renderer client object associated with this WebView.

See WebViewCompat#setWebViewRenderProcessClient(WebView,Executor,WebViewRenderProcessClient) for details, with the following differences:

Callbacks will execute directly on the thread on which this WebView was instantiated.

Passing null for webViewRenderProcessClient will clear the renderer client object for this WebView.

This method should only be called if WebViewFeature#isFeatureSupported(String) returns true for WebViewFeature#WEB_VIEW_RENDERER_CLIENT_BASIC_USAGE.

Parameters
webview	WebView: the WebView on which to monitor responsiveness.
webViewRenderProcessClient	WebViewRenderProcessClient?: the WebViewRenderProcessClient to set for callbacks.

startSafeBrowsing

open static fun startSafeBrowsing(
    @NonNull context: Context, 
    @Nullable callback: ValueCallback<Boolean!>?
): Unit

Starts Safe Browsing initialization.

URL loads are not guaranteed to be protected by Safe Browsing until after callback is invoked with true. Safe Browsing is not fully supported on all devices. For those devices callback will receive false.

This should not be called if Safe Browsing has been disabled by manifest tag or . This prepares resources used for Safe Browsing.

This should be called with the Application Context (and will always use the Application context to do its work regardless).

This method should only be called if WebViewFeature#isFeatureSupported(String) returns true for WebViewFeature#START_SAFE_BROWSING.

Parameters
context	Context: Application Context.
callback	ValueCallback<Boolean!>?: will be called on the UI thread with true if initialization is successful, false otherwise.