InAppBrowser — PhoneGap 2.3.0

About this version

This page preserves the official documentation for Version 2.3.0. Commands, supported platforms and API behavior below belong to that historical version. For active projects, consult the current Apache Cordova documentation.

Reference sections

• InAppBrowser
• window.open

InAppBrowser

The InAppBrowser is a web-browser that is shown in your app when you use the window.open call.

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

Description

The object returned from a call to window.open.

Methods

• addEventListener
• removeEventListener
• close

Permissions

Android

app/res/xml/config.xml

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

iOS

config.xml

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

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 fired when the InAppBrowser starts to load a URL 
    loadstop - event fired when the InAppBrowser finished loading a URL
    exit - event fired when the InAppBrowser window is closed 
  

• callback: the function that is called when the event is fired. The function is passed an InAppBrowserEvent object.

Supported Platforms

• Android
• iOS

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-2.3.0.js"></script>
    <script type="text/javascript" charset="utf-8">

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

    // Cordova is ready
    //
    function onDeviceReady() {
         var ref = window.open('http://apache.org', '_blank', 'location=yes');
         ref.addEventListener('loadstart', function() { alert('start: ' + event.url); });
         ref.addEventListener('loadstop', function() { alert('stop: ' + event.url); });
         ref.addEventListener('exit', function() { 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 fired when the InAppBrowser starts to load a URL 
    loadstop - event fired when the InAppBrowser finished loading a URL
    exit - event fired when the InAppBrowser window is closed 
  

• callback: the function that was to be called when the event is fired. The function is passed an InAppBrowserEvent object.

Supported Platforms

• Android
• iOS

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-2.3.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for Cordova 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 iabClose(event) {
         alert(event.type);
         iabRef.removeEventListener('loadstart', iabLoadStart);
         iabRef.removeEventListener('loadstop', iabLoadStop);
         iabRef.removeEventListener('exit', iabClose);
    }

    // Cordova is ready
    //
    function onDeviceReady() {
         iabRef = window.open('http://apache.org', '_blank', 'location=yes');
         iabRef.addEventListener('loadstart', iabLoadStart);
         iabRef.addEventListener('loadstop', iabLoadStop);
         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

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-2.3.0.js"></script>
    <script type="text/javascript" charset="utf-8">

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

    // Cordova is ready
    //
    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>

InAppBrowserEvent

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

Properties

• type: the eventname (String) - one of loadstart, loadstop, or exit
• url: the URL that was loaded (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 you have Unicode characters in your URL.

• target: the target to load the URL in (String) (Optional, Default: "_self")

    _self - opens in the Cordova WebView if url is in the white-list, else it opens in the InAppBrowser 
    _blank - always open in the InAppBrowser 
    _system - always open in the system web browser 
  

• options: options for the InAppBrowser (String) (Optional, Default: "location=yes")

  The options string must not contain any blank space, each feature name and value must be separated by a comma. Only the value below is supported:

        location - set to 'yes' or 'no' to turn the location bar on or off for the InAppBrowser
  

Supported Platforms

• Android
• iOS

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-2.3.0.js"></script>
    <script type="text/javascript" charset="utf-8">

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

    // Cordova is ready
    //
    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>