# Apache Cordova Documentation

# InAppBrowser

> The `InAppBrowser` is a web browser view that displays when calling `window.open()`, or when opening a link formed as `<a target="_blank">`.

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

NOTE: The InAppBrowser window behaves like a standard web browser, and can't access Cordova APIs.

## Description

The object returned from a call to `window.open`.

## Methods

- addEventListener
- removeEventListener
- close
- show
- executeScript
- insertCSS

## Accessing the Feature

As of version 3.0, Cordova implements device-level APIs as plugins. Use the CLI's `plugin` command, described in The Command-Line Interface, to add or remove this feature for a project:

        $ cordova plugin add org.apache.cordova.inappbrowser
        $ cordova plugin ls
        [ 'org.apache.cordova.inappbrowser' ]
        $ cordova plugin rm org.apache.cordova.inappbrowser

These commands apply to all targeted platforms, but modify the platform-specific configuration settings described below:

- Amazon Fire OS (in `res/xml/config.xml`)

      <feature name="InAppBrowser">
          <param name="android-package" value="org.apache.cordova.inappbrowser.InAppBrowser" />
      </feature>

- Android (in `res/xml/config.xml`)

      <feature name="InAppBrowser">
          <param name="android-package" value="org.apache.cordova.inappbrowser.InAppBrowser" />
      </feature>

- iOS (in the named application directory's `config.xml`)

      <feature name="InAppBrowser">
          <param name="ios-package" value="CDVInAppBrowser" />
      </feature>

- Windows Phone 7 and 8 (in `config.xml`)

      <feature name="InAppBrowser" />

Some platforms may support this feature without requiring any special configuration. See Platform Support for an overview.

# 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

- Amazon Fire OS
- Android
- BlackBerry 10
- iOS
- Windows Phone 7 and 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.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

- Amazon Fire OS
- Android
- BlackBerry 10
- iOS
- Windows Phone 7 and 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.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.addEventListener('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

- Amazon Fire OS
- Android
- BlackBerry 10
- iOS
- Windows Phone 7 and 8

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

# show

> Displays an InAppBrowser window that was opened hidden. Calling this has no effect if the InAppBrowser was already visible.

    ref.show();

- ref: reference to the InAppBrowser window (`InAppBrowser`)

## Supported Platforms

- Amazon Fire OS
- Android
- BlackBerry 10
- iOS

## Quick Example

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

## Full Example

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

        <script type="text/javascript" charset="utf-8" src="cordova.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', 'hidden=yes');
             ref.addEventListener('loadstop', function(event) {
                 alert('background window loaded');
             });
             // 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

- Amazon Fire OS
- Android
- BlackBerry 10
- iOS

## Quick Example

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

## Full Example

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

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

- Amazon Fire OS
- Android
- BlackBerry 10
- 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.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 to use as the Done button's caption.
  - hidden: set to `yes` to create the browser and load the page, but not show it. The load event fires when loading is complete. Omit or set to `no` (default) to have the browser open and load normally.
  - clearcache: set to `yes` to have the browser's cookie cache cleared before the new window is opened
  - clearsessioncache: set to `yes` to have the session cookie cache cleared before the new window is opened

  iOS only:

  - closebuttoncaption: set to a string to use as the Done button's caption. Note that you need to localize this value yourself.
  - hidden: set to `yes` to create the browser and load the page, but not show it. The load event fires when loading is complete. Omit or set to `no` (default) to have the browser open and load normally.
  - 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 in-line 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

- Amazon Fire OS
- Android
- BlackBerry 10
- iOS
- Windows Phone 7 and 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.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>