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

code_snippet_001

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) {
        $('#togglePane').addClass('hide');
        isVisible = 0;
    } else {
        $('#togglePane').removeClass('hide');
        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: