User Scripts
Supported Platforms: AndroidiOSmacOSWindows
What is a User Script? We can say that the UserScript
class is the equivalent of the WKUserScript iOS native class.
It represents a JavaScript code that the WebView injects into the web page and in any other subsequent navigated web page.
What are the advantages of using User Scripts instead of just injecting some JavaScript code with, for example, the evaluateJavascript
method?
An UserScript
gives you the possibility to inject a JavaScript code before other resources of the web page are loaded, setting the injectionTime
property, for example, to UserScriptInjectionTime.AT_DOCUMENT_START
(that is the equivalent of the WKUserScriptInjectionTime.atDocumentStart
iOS native property).
For each UserScript
, you can set an optional Content World, set whether to inject the script into the main frame using the forMainFrameOnly
property (iOS only), and a set of matching rules for the allowed origins (Android only).
Unfortunately, on Android, when using UserScriptInjectionTime.AT_DOCUMENT_START
, if the WebViewFeature.DOCUMENT_START_SCRIPT
is not supported, there is no guarantee that the JavaScript code has been injected before other resources are loaded because the corresponding native class/feature doesn't exist, so InAppWebView tries to inject that UserScript
as soon as possible.
To add a UserScript
to a WebView, you can use the WebView.initialUserScripts
property:
InAppWebView(
initialUrlRequest: URLRequest(url: WebUri('https://flutter.dev')),
initialUserScripts: UnmodifiableListView<UserScript>([
UserScript(
source: "var foo = 49;",
injectionTime: UserScriptInjectionTime.AT_DOCUMENT_START),
UserScript(
source: "var bar = 2;",
injectionTime: UserScriptInjectionTime.AT_DOCUMENT_END),
]),
onLoadStop: (controller, url) async {
var result = await controller.evaluateJavascript(source: "foo + bar");
print(result); // 51
},
),
To add or remove User Scripts, you can also use the corresponding methods, such as InAppWebViewController.addUserScript
, InAppWebViewController.removeUserScript
, etc.
Adding or removing User Scripts at runtime after a web page is loaded will take no effect until the next web page load.
For each UserScript
you can define a groupName
that you can use, for example, to remove a group of User Scripts with the InAppWebViewController.removeUserScriptsByGroupName
method.
Security
For each UserScript
, you can restrict execution using the allowedOriginRules
and forMainFrameOnly
parameters.
allowedOriginRules
represents a set of matching rules for the allowed origins.
Adding '*'
as an allowed origin or setting this to null
, it means it will allow every origin.
Instead, an empty Set
will block every origin.
NOTE for Android: each origin pattern MUST follow the table rule of PlatformInAppWebViewController.addWebMessageListener
.
NOTE for iOS, macOS, Windows: each origin pattern will be used as a Regular Expression Pattern that will be used on JavaScript side using RegExp.
forMainFrameOnly
is a boolean value that indicates whether to inject the script into the main frame.
Specify true
to inject the script only into the main frame, or false
to inject it into all frames.
The default value is true
.
Starting from plugin version >= 6.2.0-beta.1
, you can restrict also internal User Scripts (PluginScript) execution
using InAppWebViewSettings.pluginScriptsForMainFrameOnly
and InAppWebViewSettings.pluginScriptsOriginAllowList
.
They work the same way as UserScript.forMainFrameOnly
and UserScript.allowedOriginRules
parameters,
but they will apply for all the internal User Scripts.
Also, they should be set when initializing the WebView through PlatformWebViewCreationParams.initialSettings
parameter,
as setting or changing these values after the WebView has been created won't have any effect.
Both settings apply also to the JavaScript Bridge object, which is initialized using an internal User Script.
If no InAppWebViewSettings.javaScriptBridgeForMainFrameOnly
and/or InAppWebViewSettings.javaScriptBridgeOriginAllowList
are set,
then these settings will be used respectively.
The default value for InAppWebViewSettings.pluginScriptsForMainFrameOnly
is false
.
The default value for InAppWebViewSettings.pluginScriptsOriginAllowList
is null
.