InAppBrowser

The InAppBrowser is a web browser that displays in the app when calling window.open.

var ref = window.open('http://apache.org', '_blank', 'location=yes');

Description

The object returned from a call to window.open.

Methods

Permissions

Android

app/res/xml/config.xml

<plugin name="InAppBrowser" value="org.apache.cordova.InAppBrowser" />

iOS

config.xml

<plugin name="InAppBrowser" value="CDVInAppBrowser" />

Windows Phone 7 + 8

config.xml

<plugin name="InAppBrowser" />

addEventListener

Adds a listener for an event from the InAppBrowser.

ref.addEventListener(eventname, callback);

ref: reference to the InAppBrowser window (InAppBrowser)
eventname: the event to listen for (String)
- loadstart: event fires when the InAppBrowser starts to load a URL.
- loadstop: event fires when the InAppBrowser finishes loading a URL.
- loaderror: event fires when the InAppBrowser encounters an error when loading a URL.
- exit: event fires when the InAppBrowser window is closed.
callback: the function that executes when the event fires. The function is passed an InAppBrowserEvent object as a parameter.

Supported Platforms

Android
iOS
Windows Phone 7 + 8

Quick Example

var ref = window.open('http://apache.org', '_blank', 'location=yes');
ref.addEventListener('loadstart', function() { alert(event.url); });

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>InAppBrowser.addEventListener Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //
    function onDeviceReady() {
         var ref = window.open('http://apache.org', '_blank', 'location=yes');
         ref.addEventListener('loadstart', function(event) { alert('start: ' + event.url); });
         ref.addEventListener('loadstop', function(event) { alert('stop: ' + event.url); });
         ref.addEventListener('loaderror', function(event) { alert('error: ' + event.message); });
         ref.addEventListener('exit', function(event) { alert(event.type); });
    }

    </script>
  </head>
  <body>
  </body>
</html>

removeEventListener

Removes a listener for an event from the InAppBrowser.

ref.removeEventListener(eventname, callback);

ref: reference to the InAppBrowser window. (InAppBrowser)
eventname: the event to stop listening for. (String)
- loadstart: event fires when the InAppBrowser starts to load a URL.
- loadstop: event fires when the InAppBrowser finishes loading a URL.
- loaderror: event fires when the InAppBrowser encounters an error loading a URL.
- exit: event fires when the InAppBrowser window is closed.
callback: the function to execute when the event fires. The function is passed an InAppBrowserEvent object.

Supported Platforms

Android
iOS
Windows Phone 7 + 8

Quick Example

var ref = window.open('http://apache.org', '_blank', 'location=yes');
var myCallback = function() { alert(event.url); }
ref.addEventListener('loadstart', myCallback);
ref.removeEventListener('loadstart', myCallback);

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>InAppBrowser.removeEventListener Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // Global InAppBrowser reference
    var iabRef = null;

    function iabLoadStart(event) {
        alert(event.type + ' - ' + event.url);
    }

    function iabLoadStop(event) {
        alert(event.type + ' - ' + event.url);
    }

    function iabLoadError(event) {
        alert(event.type + ' - ' + event.message);
    }

    function iabClose(event) {
         alert(event.type);
         iabRef.removeEventListener('loadstart', iabLoadStart);
         iabRef.removeEventListener('loadstop', iabLoadStop);
         iabRef.removeEventListener('loaderror', iabLoadError);
         iabRef.removeEventListener('exit', iabClose);
    }

    // device APIs are available
    //
    function onDeviceReady() {
         iabRef = window.open('http://apache.org', '_blank', 'location=yes');
         iabRef.addEventListener('loadstart', iabLoadStart);
         iabRef.addEventListener('loadstop', iabLoadStop);
         iabRef.removeEventListener('loaderror', iabLoadError);
         iabRef.addEventListener('exit', iabClose);
    }

    </script>
  </head>
  <body>
  </body>
</html>

close

Closes the InAppBrowser window.

ref.close();

ref: reference to the InAppBrowser window (InAppBrowser)

Supported Platforms

Android
iOS
Windows Phone 7 + 8
BlackBerry 10

Quick Example

var ref = window.open('http://apache.org', '_blank', 'location=yes');
ref.close();

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>InAppBrowser.close Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //
    function onDeviceReady() {
         var ref = window.open('http://apache.org', '_blank', 'location=yes');
         // close InAppBrowser after 5 seconds
         setTimeout(function() {
             ref.close();
         }, 5000);
    }

    </script>
  </head>
  <body>
  </body>
</html>

executeScript

Injects JavaScript code into the InAppBrowser window

ref.executeScript(details, callback);

ref: reference to the InAppBrowser window. (InAppBrowser)
injectDetails: details of the script to run, specifying either a file or code key. (Object)
- file: URL of the script to inject.
- code: Text of the script to inject.
callback: the function that executes after the JavaScript code is injected.
- If the injected script is of type code, the callback executes with a single parameter, which is the return value of the script, wrapped in an Array. For multi-line scripts, this is the return value of the last statement, or the last expression evaluated.

Supported Platforms

Android
iOS

Quick Example

var ref = window.open('http://apache.org', '_blank', 'location=yes');
ref.addEventListener('loadstop', function() {
    ref.executeSript({file: "myscript.js"});
});

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>InAppBrowser.executeScript Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // Global InAppBrowser reference
    var iabRef = null;

    // Inject our custom JavaScript into the InAppBrowser window
    //
    function replaceHeaderImage() {
        iabRef.executeScript({
            code: "var img=document.querySelector('#header img'); img.src='http://cordova.apache.org/images/cordova_bot.png';"
        }, function() {
            alert("Image Element Successfully Hijacked");
        }
    }

    function iabClose(event) {
         iabRef.removeEventListener('loadstop', replaceHeaderImage);
         iabRef.removeEventListener('exit', iabClose);
    }

    // device APIs are available
    //
    function onDeviceReady() {
         iabRef = window.open('http://apache.org', '_blank', 'location=yes');
         iabRef.addEventListener('loadstop', replaceHeaderImage);
         iabRef.addEventListener('exit', iabClose);
    }

    </script>
  </head>
  <body>
  </body>
</html>

insertCSS

Injects CSS into the InAppBrowser window.

ref.insertCSS(details, callback);

ref: reference to the InAppBrowser window (InAppBrowser)
injectDetails: details of the script to run, specifying either a file or code key. (Object)
- file: URL of the stylesheet to inject.
- code: Text of the stylesheet to inject.
callback: the function that executes after the CSS is injected.

Supported Platforms

Android
iOS

Quick Example

var ref = window.open('http://apache.org', '_blank', 'location=yes');
ref.addEventListener('loadstop', function() {
    ref.insertCSS({file: "mystyles.css"});
});

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>InAppBrowser.insertCSS Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // Global InAppBrowser reference
    var iabRef = null;

    // Inject our custom CSS into the InAppBrowser window
    //
    function changeBackgroundColor() {
        iabRef.insertCSS({
            code: "body { background: #ffff00"
        }, function() {
            alert("Styles Altered");
        }
    }

    function iabClose(event) {
         iabRef.removeEventListener('loadstop', changeBackgroundColor);
         iabRef.removeEventListener('exit', iabClose);
    }

    // device APIs are available
    //
    function onDeviceReady() {
         iabRef = window.open('http://apache.org', '_blank', 'location=yes');
         iabRef.addEventListener('loadstop', changeBackgroundColor);
         iabRef.addEventListener('exit', iabClose);
    }

    </script>
  </head>
  <body>
  </body>
</html>

InAppBrowserEvent

The object that is passed to the callback function from an addEventListener call on an InAppBrowser object.

Properties

type: the eventname, either loadstart, loadstop, loaderror, or exit. (String)
url: the URL that was loaded. (String)
code: the error code, only in the case of loaderror. (Number)
message: the error message, only in the case of loaderror. (String)

window.open

Opens a URL in a new InAppBrowser instance, the current browser instance, or the system browser.

var ref = window.open(url, target, options);

ref: Reference to the InAppBrowser window. (InAppBrowser)
url: The URL to load (String). Call encodeURI() on this if the URL contains Unicode characters.
target: The target in which to load the URL, an optional parameter that defaults to _self. (String)
- _self: Opens in the Cordova WebView if the URL is in the white list, otherwise it opens in the InAppBrowser.
- _blank: Opens in the InAppBrowser.
- _system: Opens in the system's web browser.
options: Options for the InAppBrowser. Optional, defaulting to: location=yes. (String)

The options string must not contain any blank space, and each feature's name/value pairs must be separated by a comma. Feature names are case insensitive. All platforms support the value below:
- location: Set to yes or no to turn the InAppBrowser's location bar on or off.
Android only
- closebuttoncaption - set to a string that will be the caption for the "Done" button.
iOS only
- closebuttoncaption - set to a string that will be the caption for the "Done" button. Note that you will have to localize this value yourself.
- toolbar - set to 'yes' or 'no' to turn the toolbar on or off for the InAppBrowser (defaults to 'yes')
- enableViewportScale: Set to yes or no to prevent viewport scaling through a meta tag (defaults to no).
- mediaPlaybackRequiresUserAction: Set to yes or no to prevent HTML5 audio or video from autoplaying (defaults to no).
- allowInlineMediaPlayback: Set to yes or no to allow inline HTML5 media playback, displaying within the browser window rather than a device-specific playback interface. The HTML's video element must also include the webkit-playsinline attribute (defaults to no)
- keyboardDisplayRequiresUserAction: Set to yes or no to open the keyboard when form elements receive focus via JavaScript's focus() call (defaults to yes).
- suppressesIncrementalRendering: Set to yes or no to wait until all new view content is received before being rendered (defaults to no).
- presentationstyle: Set to pagesheet, formsheet or fullscreen to set the presentation style (defaults to fullscreen).
- transitionstyle: Set to fliphorizontal, crossdissolve or coververtical to set the transition style (defaults to coververtical).

Supported Platforms

Android
iOS
BlackBerry 10
Windows Phone 7 + 8

Quick Example

var ref = window.open('http://apache.org', '_blank', 'location=yes');
var ref2 = window.open(encodeURI('http://ja.m.wikipedia.org/wiki/ハングル'), '_blank', 'location=yes');

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>window.open Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //
    function onDeviceReady() {
        // external url
        var ref = window.open(encodeURI('http://apache.org'), '_blank', 'location=yes');
        // relative document
        ref = window.open('next.html', '_self');
    }

    </script>
  </head>
  <body>
  </body>
</html>

InAppBrowser

API Reference

Guides

Android

app/res/xml/config.xml

iOS

config.xml

Windows Phone 7 + 8

config.xml

Android only

iOS only