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	`setSafeBrowsingAllowlist(@NonNull hosts: MutableSet<String!>, @Nullable callback: ValueCallback<Boolean!>?)` Configures a set of hosts (domain names/IP addresses) that are exempt from SafeBrowsing checks.
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:

// Web page (in JavaScript)
      // message needs to be a JavaScript String, 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 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 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);
      }

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