#phonegapbuild

This past weekend, I upgraded my iPhone to iOS 10.2.  All was well, until I happened to open one of my PhoneGap apps and saw some weird freezing issues.  Upon further investigation, they were Content Security Policy issues, seen in Console output as:

Refused to load frame 'gap://ready' because it violates the following Content Security Policy directive: "default-src *". For reference, in PhoneGap Build, I’m using PhoneGap version cli-6.3.0 (iOS 4.2.0 / Android 5.2.1 / Windows 4.4.1).  

It appears as though in one of the recent iOS 10.X updates, Content Security Policies became stricter under the UIWebView (they're already like that if you use the newer WKWebView).

Not fun (and fortunately, rare) to have an OS upgrade completely break an app! Fortunately, the fix was straight forward.

In index.html, I had:  default-src *;

I changed it to: default-src 'self’ gap:;

I had: (no connect-src directive)

I added a "connect-src" directive, needing to allow connections to Fitbit’s API. Just specifying the root URL works here - no need to specify every single endpoint:  connect-src: https://api.fitbit.com;

I had: (no img-src directive)

I added an "img-src" directive, which allows external images to be loaded:     img-src * data:;

Here's the final CSP my app is using.  Note that your app may need different values! For more details, Mozilla has great documentation.

In just a few days (November 15th, 2016), PhoneGap Build's plugin directory is going away in favor of Node Package Manager (NPM).  No need to panic! There are several paths you can take to move over to NPM.

Option 1 - "I'm using a popular plugin": Use NPM referral link

In a great move, PG Build has given us the option to see the plugin's equivalent on NPM or submit a suggestion ourselves.

Navigate to the StatusBar plugin page for example.  Here, we see a link to the most likely (submitted by users, so may not be correct!) equivalent plugin on NPM: 

Clicking the “probably here” link brings us over to NPM.  Most, especially official, PhoneGap plugins begin with “cordova-plugin” so usually it’s safe to assume that they are equivalent.  As we’ll see below though, that’s not always the case - review the NPM one in detail and test it before putting out a new version of your app.

In our config.xml, replace the PhoneGap Build version with the updated NPM one:

<plugin name="cordova-plugin-statusbar" spec="2.1.3" source="npm" />

NPM link not there? If you happen to know the NPM equivalent, please consider helping others out by submitting it's module name at the bottom of the plugin page. For example, I'm using the PG Build Google Analytics plugin, but found and submitted cordova-plugin-google-analytics as it's replacement.

Option 2 - No "NPM referral link" on PG plugins page: Find plugin on NPM

In this new world, you need to use NPM: https://www.npmjs.com/.  PhoneGap/Cordova plugins generally begin with "cordova-plugin" in their names, so begin your search with that coupled with whatever you're looking for: cordova-plugin-something-cool.  When you find a plugin, the latest version number to use will be seen on the right hand side of the page: 

In this example, the config.xml reference should be:

<plugin name="cordova-plugin-google-analytics" spec="1.7.1" source="npm" />

Option 3 - Last Ditch Option: Fork from GitHub

What is there is no referral link and/or you can't find an equivalent on NPM? Fork it from GitHub to your personal account and reference it from there.  This also works in the case that the NPM plugin is not quite the same as the PGB one and you don't have time to update your code just yet.  I actually needed to do this step for the Google Analytics plugin - it turns out the namespaces and methods are slightly different. I'll update the code eventually, but I want to ship out some other changes shortly.

Navigate to the plugin page on PG Build. Under "Other Details", you'll see a Repository link:

Copy the link.  Over in your config.xml, your old reference probably looks like:

<gap:plugin name="com.adobe.plugins.gaplugin" version="2.4.0" />

Change it to point to the GitHub version using source="git" and name to spec. On a new app build, PGB pulls the code from GitHub now:

<plugin spec="https://github.com/phonegap-build/GAPlugin" source="git" />

As a final step, consider forking the repository for future reference or to maintain a copy in case it's deleted.  Navigate to the repository's GitHub page, then click the Fork button in the upper right hand corner. The repository now appears in your account as a "forked repository".  When I navigate to my forked version of GAPlugin now, it's essentially copied/saved for future reference: https://github.com/dotNetkow/GAPlugin

I’m in the midst of wrapping up my first Pluralsight course on PhoneGap Build Fundamentals and stumbled upon this today: if you include a special file into each icon and splash screen image directory, PhoneGap Build will only include the platform specific icon/splash files in each app binary created.

For years now (and I suspect I’m far from the only one), I’ve assumed that PG Build already does since, since we specify the image file paths in the config.xml file.  Nope!  All images are always included.  Include a PGB Omit file with no file extension (.pgbomit) into each icon/splash directory.  I tested it with the app I’m building for the course:

Before: 6.4MB

After: 3.3MB

Basically half of the original size! Awesome.

Details can be found at the newly revamped PhoneGap docs page:

I encountered a frustrating issue the other day after upgrading to PhoneGap version cli-5.2.0 on Android.  My requests to Fitbit's API began to fail, resulting in 404 errors. I was incredibly stumped - the exact same code worked fine on iOS.  I ran the code on my iPhone and my Android tablet and pulled up both requests side by side.  All details in the requests were the same: URL, HTTP method, etc.  Everything except the status code - 200 OK for iOS and 404 Not Found (from cache) for Android.

Why a 404, specifically? Was something wrong on Fitbit's end?  Couldn't be - it went through on Android.  Finally it hit me - "(from cache)"?  That's odd!  After some Google searches, I had the answer.

As the Cordova docs explain, the more recent PhoneGap "cli" type versions coupled with Android's security model require the Cordova whitelist plugin.  I was testing on an Android 4.4 device, so that makes sense.  What the first link doesn't explain, but this blog post does, is that "Network requests are blocked by default without the plugin."  Ok then!

After installing the whitelist plugin and rerunning my code, I got an error pop-up with the following message:

"SecurityError: Refused to load the script 'https://api.fitbit.com/' because it violates the document's Content Security Policy."

The whitelist plugin docs explain that there are 4 types of security policies to be aware of:

Navigation: Controls which URLs the WebView itself can navigate to

Intent: Controls which URLs the app is allowed to ask the system to open.  This doesn’t apply to plugins - only hyperlinks and calls to window.open( )

Network Request: Controls which network requests (images, XHR/HTTP) are allowed to be made via Cordova native hooks.

Content Security Policy: Controls which network requests (images, XHR/HTTP) are allowed to be made via the webview directly.

I load images and make REST API calls via the webview directly, so I needed a CSP.  After much fiddling, consulting links like this one, I got it to work.  Add this to your index.html page to the <head> element:

<meta http-equiv="Content-Security-Policy" content="default-src *; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-eval' 'unsafe-inline'; media-src *">

Yes, the "unsafe" portions are troubling, but apparently they are required for PhoneGap to work properly. 

Additionally, I needed the Network Request portion, which is set in config.xml:

<access origin="*://*.fitbit.com/*" />

<access origin="*://*.cloudfront.net/*" />    (Fitbit profile images hosted here)

You’ll be tempted to just use origin=“*” (asterisk to allow all requests) but keep your app secure by explicitly allowing access only from the resources you will connect to!

After a couple of months without building my apps on PhoneGap Build, I came back to the site only to see build errors.  Very strange, as all of my certificates and keys were valid.  On the PhoneGap community forums, others had the same issue.

TLDR; Re-export your developer certificate (.p12 file) from Keychain Access on your Mac in addition to creating a new Provisioning Profile from developer.apple.com.

The PhoneGap Build documentation for "Certificate doesn't match profile" states that you should try regenerating the provisioning file.  However, I found that exporting a new copy of my developer certificate from the Keychain app did the trick!

My best guess for why this happened is that PhoneGap Build must have updated something on their end.  This could be the case with Apple too - maybe there is newer metadata included when we re-export the p12? We may never know, but I'm hopeful this will help others in the future!

Plugins are an incredibly useful way to bring native functionality to PhoneGap apps. Once you start including them though, complexity can skyrocket, mainly because you are now dependent on actual devices to test. This can lead to frustration as feedback loops are increased. To help shorten these, follow these tips:

Practice safe programming practices: add a check that the plugin exists before attempting to use it: 

if (window.plugins !== undefined && window.plugins.myPlugin !== undefined) {

// safe to use plugin now

}

Without those, app may unexpectedly crash/become unresponsive.

Read the plugin documentation carefully. It's easy to miss a required parameter (especially with JavaScript's lack of static typing), setup steps, or even object casing ("gaPlugin" vs. "GAPlugin"). Also beware that the docs may be out of date - if you are following instructions perfectly but still have trouble try checking the plugin's open issues section if available. Oftentimes out of date documentation has been noticed by someone else, but the project leader hasn't accepted the pull request that fixes it yet. I've had this happen two separate times!

Use various tools to troubleshoot issues.

a. Local debugging: Open the app in a browser locally - are there script errors or other issues that may make the plugin issue a red herring?

b. Remote debugging: Add extra console logging messages and exception handling to narrow down the issue directly.

The PhoneGap App is a great new addition to Adobe's suite of PhoneGap tools.  It allows you to seamlessly push new code to a native device, resulting in much faster development, whether you are building PhoneGap locally or in the cloud.  What is not immediately obvious is how PhoneGap Build users can leverage it, if at all.  Well, fortunately, we can!

Unfortunately, you can’t just point the tool at your existing app directory like I’d hoped and run it. You'll need to run the “phonegap create [my-app]” command first (where [my-app] is the name of the app and subsequent folder that is created).  This creates a bunch of template files and folders.  The key here is the “www” folder: this is where your existing Build code should go.

I reached out to PhoneGap a month or so ago, asking to be featured and/or write a guest blog post.  They were fantastic to work with and very excited to share my post:

Creating a Top 5 Fitness App with PhoneGap Build