Tutorial: Phonegap Build external webpage in iframe with whitelist example

https://pixabay.com/photo-25490/Source Code & Working Example

In the last few months, the architecture `du jour` has been to create an app that open webpages. This tutorial shows you how to do that for Cordova/Phonegap. The example is written for Phonegap Build, but will work with CLI with minor modification.

The sections below include:

  • Mobile App Caveat – Something every hybrid mobile developer should know.
  • Opening and Closing a URL – Deals with the mechanics of HTML and Javascript.
  • Addressing Security Concerns – How to secure your app when opening a URL.

Mobile App Caveat

Putting aside the security concerns, the most difficult part for mobile developers is that your app may be rejected by the “app stores” – if you do this.

Quote Google Developer Program PoliciesSpam and Placement in the Store

Do not post an app where the primary functionality is to:

  • Drive affiliate traffic to a website or
  • Provide a webview of a website not owned or administered by you (unless you have permission from the website owner/administrator to do so)

Quote Apple iTunes Guidelines – 2.12

Apps that are not very useful, unique, are simply web sites bundled as Apps, or do not provide any lasting entertainment value may be rejected

In addition there is the android-block-pre-4.1.1:

Beginning May 9, 2016, Google Play will block publishing of any new apps or updates that use pre-4.1.1 versions of Apache Cordova.

Google’s Official Alert: How to fix apps with Apache Cordova vulnerabilities

Opening and Closing a URL

This section deals with the mechanics of HTML and Javascript to show an external webpage. In addition, more notes are available in the README.md and the source code.

The code that toggles the iframe uses zepto.js, a light weight jquery clone alternative. The code is listed below; just below is a button. Notice this is not a <submit> element as *was* previously used to create a buttons with HTML forms. This is an HTML5 button and zepto.js working together.

<button id=toggle>toggle</button>

Next, the iframe is wrapped with a <div>. This is where we hide the external webpage (http://cordova.apache.org/blog/). The <div> is initially set to class=hide. This hides the <div> and any children that it has; include the iframe. This class uses the CSS attribue display=none to accomplish this (See: app.css).


Below is the mechanics that make the <div> hide and show the external webpage in the iframe. It has one (1) global variable, that can easily be scoped. And as can be seen, if the element isVisible, then removeClass() else addClass(). The variable isVisible keeps track of our state.

var isVisible = 0; // if element initially hidden, zero (0) else one (1)
$('#toggle').on('click', function() {
    console.log("isVisible:" + isVisible );
    if (isVisible) {
        isVisible = 0;
    } else {
        isVisible = 1;

Next, when testing the working example, you will likely notice a small side effect. The “sided effect” is that the webpage does not load until the hidden <div> is exposed (or has the ‘hide’ class removed). Pre-loading the page is available, but is beyond the scope of this tutorial.

Addressing Security Concerns

At this point in order to appease the “stores”, you will need to use an appropriate whitelist setting. This requires the whitelist plugin and the <allow-navigation> tag with Andoird and <access origin=(...)> for iOS.

The plugin entry in the config.xml should look like this:

 <plugin name="cordova-plugin-whitelist" source="npm" />

The <allow-navigation> tags needed should look like this:

<allow-navigation href="http://cordova.apache.org/" />
<allow-navigation href="https://slack.cordova.io" />
<allow-navigation href="http://www.google-analytics.com/" />
<allow-navigation href="https://*.imgur.com/" />
<allow-navigation href="https://*.twitter.com/" />
<allow-navigation href="https://*.twimg.com/" />
<allow-navigation href="http://cordovablogs.discus.com/" />

What is not immediately apparent is that all the domains listed are required so that the one external webpage will be rendered correctly. Generally, the list of the domains can be extracted by looking at the source, but sometimes you’ll need to open the “information page” for that webpage. On firefox, that is ctrl-i.

Last but not least, is the <access> tag. This is set to the “wild card”, which will allow anything through. To secure the app better, this should mirror the the entry for allow-navigations.

<access origin="*" />

If you have any question, please use the comment section below, or find me on Google Group for Cordova/Phonegap.

For more detailed information on the whitelist and the plugin, read:

Ten (10) Phonegap Demo Apps with Source Code

For those unaware, I’ve been busy the last few months helping my parents move from California to Texas. In the meantime, among other things I have created 10+ Phonegap Apps1, each of which uses at least one Phonegap core APIs. In addition all the Apps run in Android and iOS devices – within the restraints of the devices 2.


Other goals for these apps:

  • NO JQuery or similar libraries
  • Find the minimum necessary for a phonegap App

These Phonegap Apps are both demos and tutorials. At this point, the apps are operational, but are far from perfect. Over the last few days I have added some changes that give the apps a more professional appearance.

Accelerometer App

Network App

Contacts App

Device App

The Changes

Those changes include:

  • added the plugin device to all Apps
  • added id to the [exit] button and the App header
  • moved CSS style tags from the elements to the head
  • added code to remove the [exit] button from the iOS version
  • removed a CSS coding error
  • removed <span> where unneeded

The following changes still need to be made:

  • Add fastclick.js to remove the 300ms delay
  • Add margin to top of document body to support post-iOS-73
  • Remove all margins from top header
  • Add elements to standardize the header

Future projects scheduled for release are:

  • working boilerplates for rapid development
  • minimual UI libraries for notifications, sliding panels, & div-tables
  • minimual implementation of various phonegap plugins


  1. http://codesnippets.altervista.org/examples/phonegap/demos/PUBLIC.Apps.html
  2. Some devices do not have the hardware needed for an API, ie. compass.
  3. After iOS7 a change was made to make system status bar transparent. This cause a program to display over the system status bar.