WebViewCompat
open class WebViewCompat
kotlin.Any | |
↳ | androidx.webkit.WebViewCompat |
Compatibility version of android.webkit.WebView
Summary
Nested classes | |
---|---|
abstract |
Callback interface supplied to |
abstract |
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 |
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 |
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 |
Returns true if |
open static Unit |
postVisualStateCallback(@NonNull webview: WebView, requestId: Long, @NonNull callback: WebViewCompat.VisualStateCallback) Posts a |
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 |
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. |
|
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. |
|
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. |
|
Custom scheme | SCHEME is a custom scheme; HOSTNAME_PATTERN and PORT must not be present. |
|
* |
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