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).

Note for Android

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.

info

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.

info

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.