This version of Astro is only compatible with Xcode 7.3

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

WebViewPlugin.init().then(function(webView) {



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 page timeout event is fired.

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.

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.


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', function(params) {
    if (params.url == '') {
        alert('Welcome back home');
    if (!params.canGoBack) {
        alert('You are at the root');


noInternetConnection → {url} #

Fires when the plugin attempts to navigate but there is no internet connection.

Sample usage:

webView.on('noInternetConnection', function(params) {

pageTimeout #

Fires when the plugin has been trying to load content for longer than the page timeout duration.

Sample usage:

webView.on('pageTimeout', function() {

navigationCompleted #

Fires when the web view has finished loading the page.

Sample usage:

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

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.