Forge v2.6 Migration Guide

header-image Forge v2.6 Migration Guide

This year we’ve tried something different by synchronizing the next major Forge update with both the latest Android “Oreo” and iOS 11 releases.

In future we’ll continue to synchronize both our Android and iOS updates to Apple’s annual release cadence. This will see a new major version released every year in the first few weeks of September.

What this means for our customers is that, here on out, you will be able to rely on us to follow a predictable release cycle.

Being able to schedule the testing & updates for your apps well in advance and on both operating systems concurrently will reduce your costs considerably while increasing everyone’s happiness.

A reason to smile :-)

We’re also happy to announce that the latest Android and iOS releases have far less changes this year affecting Trigger.IO apps directly.

We’ll go into more detail below but the major changes you need to be aware of are:

  • iOS now requires a 1024x1024 pixel Marketing Icon.
  • A number of modules will need to be updated to the latest versions: display, file, icons, launchimage, notification, parse, platform, request, tabbar, tabs, topbar and tribr_multi_image_select.
  • Google have restricted some Android WebView API’s from working with content served directly off the device filesystem. This may require your app to use the httpd module.
  • The iPhone-X features rounded corners and a “notch” which can complicate page layout on iOS.
  • The minimum Android version supported is now: Android API Level 14.
  • The minimum iOS version supported is now: iOS 9.3
  • The proprietary facebook module has been deprecated in favour of a standards-based OAuth 2.0 solution.
  • The crosswalk build target has been updated to: 23.53.589.4 (Please note that Intel have announced they will no longer be maintaining the project so this is in all likelihood the final update the target will receive.)

The best part of the improved backwards compatibility achieved by Apple & Google this year is that we got to spend more time on new features we think you’ll love and give you even more reasons to smile!

These include:

  • Experimental support for iOS WKWebView. (For real this time!)
  • Experimental support for JavaScript ES6 Promises.
  • A complete overhaul of the forge.request module with full HTTP/2 & SNI support and better compatibility with Android 4.x devices.
  • A new module, forge.fs, which provides a full device filesystem API and file picker that is no longer limited to images & videos.
  • A new module, forge.oauth, which provides an “OAuth 2.0 for Native Apps” implementation.

We’ll be releasing detailed tutorials for each of the new modules in the upcoming weeks.

For now, let’s take a detailed look at the steps needed to update your app for Forge Platform v2.6.

Step 1: update to 2.6.3

Edit your app’s src/config.json file and set:

Step 2: update modules

Edit your app’s src/config.json file and, for the modules you use, update as follows:


  • Update to "version": "2.8"


  • Update to "version": "2.18"


  • Update to "version": "2.8"
  • Add a new 1024×1024 marketing icon for ios:


  • Update to "version": "2.13"


  • Update to "version": "2.5"


  • Update to "version": "2.8"


  • Update to "version": "2.17"


  • Update to "version": "2.3"


  • Update to "version": "2.10"
  • While every effort has been made to ensure backwards compatibility it is possible that you may run into some subtle differences in behaviour. If you do run into any issues please get hold of us on!


  • Update to "version": "2.6"


  • Update to "version": "2.18"


  • Update to "version": "2.13"


  • Update to "version": "1.4"

Optional: configure content inset behavior on the iPhone-X

To accommodate the rounded corners and “notch” of the iPhone-X Apple have introduced the idea of so-called “safe areas”.

By default Forge apps will limit the accessible portion of your app’s web view to the following area defined by the notch and corners:

iPhone-X Safe Area

To give your app full access to the full extent of the webview you will need set the content insets as follows:

Optional: enable httpd module

Historically Forge apps have served their content directly from the device filesystem using the file:// scheme.

Over time this has created more and more problems as Google or Apple continue to introduce restrictions targeting the http:// and https:// schemes without considering their impact on other RFC 1630 URL types.

With the latest version of Android “Oreo” 8.0 (API level 26) we’ve identified the following features that are directly impacted by this:

  • WebSockets
  • IndexedDB

If your app uses one or more of these features you will need to enable the httpd module for your app.

Edit your app’s src/config.json file to give Forge access to http://localhost/* URL’s:

…and then add the httpd module:

It is unlikely that this trend will reverse so in the future we will be compiling the httpd module in by default and deprecating support for loading content directly from the device filesystem.

You can find more information on this community forum thread: Issues with IndexedDB & WebSockets on Android

Optional: replace facebook module with oauth module

If you are currently using the facebook module, this will be the hardest part of the migration.

The steps involved boil down to:

  1. Remove the facebook module from your app.
  2. Add the oauth module to your app.
  3. Configure the oauth module’s providers section with your Facebook credentials.
  4. Set up a static web page to handle the OAuth redirect call from Facebook.
  5. Replace any Facebook module API calls with calls to the Facebook REST API’s and the share module.

We’ll be releasing an in-depth guide over the next few weeks but, for the very brave, we have an example on the module documentation page.

Finally, if you’re in a hurry and don’t want to wait, please reach out to us on We’ll be happy to answer your questions and provide assistance with migration.

Optional: enable experimental support for iOS WKWebView

With iOS 11 Apple have finally addressed the many long-standing issues preventing WKWebView from being a full replacement for UIWebView.

You can enable experimental WKWebView support for your app by editing your app’s src/config.json file:

If your app makes use of XHR requests (e.g. for Ajax or dynamic script includes) you will also need to add the httpd module as Apple have restricted WKWebView to only allow XHR requests from CORS-configured endpoints. See the Optional: enable httpd module section above for instructions.

The WKWebView features required to integrate fully with Forge are only available on iOS 11 devices so the default behavior is to automatically fall back to UIWebView on earlier iOS devices.

You can force WKWebView to be used on older iOS devices as well by adding the following flags configuration:

Please note that some Forge features can not be supported in this configuration.

Amongst other issues, you will find that you are unable to embed content from your device’s asset stores in your app.

Optional: enable experimental support for JavaScript ES6 Promises

Open your app’s src/config.json file and add a new top-level section as follows:

Now you can finally replace this:

…with this:

Yay! 😄

We’ve bundled a Polyfill for backwards-compatibility so this should also work on older Android and iOS versions.

For more info, check out: “JavaScript Promises: an Introduction”


New Android and iOS releases are always a little stressful. Please don’t hesitate to join us on the Forge 2.6 Community Forum Topic if you have any questions around the update process or run into any difficulties!