Web View Plugin

The web view plugin is a simple web browser plugin. The plugin can display any page (both remote and locally bundled). Events are fired as the plugin navigates.

Note If you want to support more advanced features, like "fast back" (aka stacking), you should use the NavigationPlugin instead.

User Agent

The plugin modifies the User Agent and adds Astro App/1.0 to all requests (1.0 is replaced with version number of the native app hosting Astro). The application version can be retrieved from any Astro javascript code by accessing the property Astro.applicationVersion.


On iOS the version number is the CFBundleVersionShortString in the application's info.plist.


On Android the version number is the value returned from calling getPackageManager.getPackageInfo(getPackageName(), 0).versionName. This value can be set in build.gradle.

Sample Usage

const webView = await WebViewPlugin.init()



WebViewPlugin.init(options) #

Creates and returns an instance of the web view plugin that is used to make subsequent method calls.


getLoader() #

Returns the loader instance for this web view plugin instance.

setLoaderPlugin(loaderPlugin) #

Sets a loader plugin that will be displayed while the web view is navigating.

See also manuallyShowPageForHosts and showPage which can be used to manually control when the configured loader plugin is dismissed.


navigate(url, options) #

Navigates to the specified url.

back() #

Navigates back, if possible.

reload() #

Reloads the current page.

disableDefaultNavigationHandler() #

Disables default navigation. Navigation will be canceled after calling this method unless you bind to the navigate event and explicitly call navigate(url) yourself.

enableDefaultNavigationHandler() #

Enables default navigation. Navigation will be handled automatically. You may still bind to the navigate event to be be notified of navigations.

setPageTimeoutDuration(timeoutDuration) #

Sets the time limit until a navigation failed event is fired. If this event is fired because of a timeout, the error property in the parameters will be populated accordingly, with error codes from Astro Event Error Codes.

Note: This method controls the raising of the navigationFailed event due to timeout which only fires under two conditions:

  1. You have set up manuallyShowPageForHosts and forgot to call showPage().
  2. The timeoutDuration you pass to this method is longer than the underlying OS network timeout (which varies between iOS and Android).

canGoBack() #

Returns a boolean for whether or not you can go back in the webview.


manuallyShowPageForHosts(hosts) #

Set the hosts for which a page should not automatically be shown when it finishes loading. You must explicitly call showPage() for these pages.

Note: You should handle the navigationFailed event and check the error for the timeout error if you use this feature!

showPage() #

Manually show the current page when you know it's finished loading. This is useful when the page you are navigating to does custom work to render itself after the page has initially loaded (i.e. sites that use adaptive.js).


enableScrollBounce() #

Enables the scroll bar to bounce past the top and bottom edges of the page.

disableScrollBounce() #

Blocks the scroll bar from bouncing past the top and bottom edges of the page.

enableScrolling() #

Enables scrolling for the web view.

disableScrolling() #

Disables scrolling for the web view.

enableLoader() #

Enables showing the loader plugin while navigating. This is the default behaviour.

disableLoader() #

Disables showing the loader plugin while navigating.


getCookie(cookieName) #

Gets the value of the cookie specified by cookieName or returns null if the cookie isn't set.

Visual appearance

setBackgroundColor(color) #

Sets the background color during transitions.

showScrollBars() #

Shows scroll bars for all web views in the stack, and all future web views.

hideScrollBars() #

Hides scroll bars for all web views in the stack, and all future web views.


navigate → {url, isCurrentlyLoading} #

Fires for every forward navigation. This could be user initiated, or a redirect. If you override the default navigation handler, you are in charge of calling navigate when the web view isn't redirecting (ie. params.isCurrentlyLoading === false)

Sample usage:

webView.on('navigate', function(params) {
    if (!/^http(s)?:\/\/ {
    } else if (!params.isCurrentlyLoading) {

back → {url, canGoBack} #

Fires for every back navigation. This typically happens when webview.back() has been called or, on iOS, the user swipes from the left edge. Note: This event will not get fired if JavaScript calls window.history.back() inside of a webview.

Sample usage:

webView.on('back', (params) => {
    if (params.url == '') {
        alert('Welcome back home')

    if (!params.canGoBack) {
        alert('You are at the root')

navigationCompleted → {url} #

Fires when the web view has finished loading the page.

Sample usage:

webView.on('navigationCompleted', (params) => {
    console.log(params.url + ' has finished loading!')

navigationFailed → {url, error} #`

Fires when the web view encounters an error loading the requested page. This event will have an error that specifies why the navigation failed.

Sample usage:

webView.on('navigationFailed', (params) => {
    console.log(params.url + ' failed to load!')
    //If there's an error to be reported, it's here:
    console.log("Error " + params.error.description)
    console.log("Error code " + params.error.code)

Note: This event is not fired if the navigation is cancelled because the web view is destroyed while there is an existing, in-process navigation. This can happen when using the WebViewPlugin in a NavigationPlugin and the user navigates back before the navigation completes.

Additional Properties

useWKWebView (iOS only) #

WKWebView is Apple's newest web rendering component and is designed to replace UIWebview. The fundamental difference between UIWebView and WKWebView is that WKWebView uses the same rendering and JavaScript engine as mobile Safari. This results in better performance and more standard web behaviour.

Note: WKWebView was introduced in iOS 8. Sadly, due to many bugs that cannot be worked around, Astro cannot use WKWebView on iOS 8. As a result, setting the useWKWebView to true has no effect in an Astro app (you should still set useWKWebView to true though, as that will result in WKWebView being used on iOS 9+ and UIWebView on iOS 8).

For a more in depth explanation of the pros and cons of using WKWebView in Astro see WebView Options In iOS.

On iOS 9, and later, Astro defaults to using the UIWebView for the worker (app.js host) and WKWebView for all other web components. On iOS 8, Astro can only use the UIWebView for all web components. If you experience problems with WKWebView on iOS 9+ platforms, you can switch back to UIWebView instead by adding the following line in your AppDelegate's application:didFinishLaunchingWithOptions: method:

AstroConfig.useWKWebView = false

uiWebViewKeyboardDisplayRequiresUserAction (iOS & UIWebView only) #

When using UIWebView, a user initiated event must happen in order for the keyboard to be displayed. If you wish to programmatically display the keyboard, you must set the keyboardDisplayRequiresUserAction property to false. We provide a flag on the AstroConfig object that allows you to set this property.

Place the following line in your AppDelegate's application:didFinishLaunchingWithOptions: method:

AstroConfig.uiWebViewKeyboardDisplayRequiresUserAction = false

If you are using WKWebView, there is currently no way to display the keyboard programmatically (as described here).

allowUntrustedHTTPSCertificate (iOS only) #

Setting this flag will allow your app to load https requests from servers that use untrusted https certificates. This is obviously dangerous and so Astro ignores this setting in RELEASE builds. This flag is included solely so that you can develop your app without having a valid ssl certificate on the sites your app is connecting to (typical for QA/testing environments). This also lets you use proxies such as Charles (which makes use of a self-signed certificate which is untrusted by default).

To allow untrusted SSL certificates, place the following in your AppDelegate's application:didFinishLaunchingWithOptions: method:

    // This is dangerous to allow outside of debug builds, don't do it!
    AstroConfig.allowUntrustedHTTPSCertificate = true

allowExplicitNavigation(urlPatterns) (iOS only) #

Adds url patterns to suppress Astro navigation handler.

If url the webView is trying to navigate to matches any of the patterns, the Astro navigation event wouldn't fire and the webView will try to handle it instead (i.e. navigation to frames with target="_frame")

Not implemented on Android since webView handles target attribute correctly there.

Astro Event Error Codes #

The WebViewPlugin module has an errorCodes property that has the following fields:

pageTimeout #

The pageTimeout error code is set when the webview failed to load in the required time. Its defined value is -1001.

noInternetConnection #

The noInternetConnection error code is set when the webview failed to load because of a connectivity issues. Its defined value is -1009.