Trigger.io Forge v2.5 and iOS 10 Migration Guide

---

Hey Trigger peeps!

The iOS 10 launch is upon us and it’s time to release the next major Forge platform update.

Every year Apple blesses us with some changes and, being a conscientious cross-platform framework provider, we do our best to minimize the impact on your team.

The shift is usually transparent but this year a few fundamentals have changed and will require a bit of work to get your app ready for iOS 10:

• iOS 10 now requires app permission dialogs to display a short usage description explaining why it requires access to device features such as the camera, contacts and calendar.
• iOS LaunchImages are no longer organized according to device screen resolution. Instead, they are now assigned to size classes. This is good news as it means that the number of separate image files required for iOS have gone down from 13 to only 4.
• Apple are getting serious about App Transport Security (ATS) and, as of 01 January 2017, its use will be mandatory for all App Store submissions. If you are using the request module and your backend infrastructure is still running HTTP or not configured to modern SSL standards your app will be affected.

Let’s take a quick look at each of these and the steps you will need to take to update your app for Forge Platform v2.5.x.

Module upgrades for iOS 10

If you are using any of the following modules you will need to make sure they are on the latest version:

Module	Min Version	Notes
calendar	2.8	Requires a usage_description entry
contact	2.10	Requires a usage_description entry
file	2.12	Requires a usage_description entry
tribr_multi_image_select	1.3	Requires a usage_description entry
launchimage	2.10	Requires new launch images
request	2.8	Requires App Transport Security (ATS) configuration
icons	2.7	Requires an iPad Pro icon (167x167px)
barcode	2.5	No app changes required

Add usage descriptions to your module configuration

iOS 10 requires app permission dialogs to display a short usage description explaining why it requires access to device features such as the camera, contacts and calendar:

The affected modules are:

• calendar – Requires a usage description for Calendars access.
• contact – Requires a usage description for Contacts access.
• file – Requires a usage description for Camera, Microphone and Photo Library access.
• tribr_multi_image_select – Requires a usage description for Photo Library access.

To configure the usage description for each of the modules you can fill in the usage_description field in the config section of src/config.json or the module configuration page in the Toolkit.

For example, to configure the calendar module you can either edit your app’s src/config.json file directly:

…or you can access the configuration through the Toolkit:

Please note that trying to your app on iOS 10 without a usage description will result in your app exiting immediately when its API methods are invoked!

iOS LaunchImage Size Classes

Apple introduced the concept of adaptive layout in iOS 8 already but, as hybrid devs, we haven’t really been affected as it only applied to native user interfaces.

With the release of iOS 10 however Apple are now requiring the use of Storyboards for App launch screens which means that the old system of having a different launch image for each device pixel resolution falls away.

Instead, there are now only four launch images, one for each Size Class defined in Apple’s adaptive layout framework.

When you App launches, iOS will select the corresponding launch image for the Size Class corresponding to the type of device running the app and its orientation.

Step 1: Upgrade the launchimage module to v2.10

Please make a note of the settings for your Android launchimage configuration before updating!

With the breaking changes for iOS we took the opportunity to do a long-needed re-organization of the module configuration schema and give the properties for Android their own section.

Step 2: Generate new launch images for each size class

The concept of size classes can be somewhat confusing at first but we can get away with only needing to remember that there are four size classes and they are applied as follows:

Size Class	Device	Landscape	Portrait	Image Size
width: Compact height: Compact	iPhone	x		1334 x 750px
width: Compact height: Regular	iPhone, iPhone Plus		x	1080 x 1920px
width: Regular height: Compact	iPhone Plus	x		1920 x 1080px
width: Regular height: Regular	iPad	x	x	2732 x 2048px

Step 3: Configure the launchimage module

Finally, to configure the launchimage module you can either use the Toolkit or simply edit your app’s src/config.json file to look something like:

For more information please see the launchimage module documentation.

App Transport Security (ATS)

In a nutshell, App Transport Security (ATS) is a requirement that all iOS App communication with remote servers via the request module use the HTTPS protocol and conform to the following minimum requirements:

• Encrypted using AES-128 or better.
• SHA-2 for certificates with either a 2048 bit or greater RSA key, or a 256 bit or greater Elliptic-Curve (ECC) key.
• Tansport Layer Security (TLS) protocol must be v1.2 or greater.
• All connection ciphers must be using forward secrecy.

This only applies to communication via the request module. Network access from the iOS WebView is still exempt from ATS.

Step 1: Upgrade the request module to v2.8

If you are already using HTTPS conforming to Apple’s security requirements for all communication with your backend infrastructure this is all you’ll have to do.

If you are still relying on HTTP for communication with backend infrastructure you will want to read the next steps!

Step 2: Disable ATS for development

Unless you are ready to roll-out SSL across your backend by this afternoon you’ll probably want a way to disable ATS during development.

Please be aware that submitting any iOS App built with this setting enabled to the App Store after 1 January 2017 will result in immediate rejection.

To disable ATS you can either edit your app’s src/config.json file:

…or modify the configuration via the Toolkit:

Step 3: Make a plan to upgrade your backend infrastructure to HTTPS

The most common obstacle to upgrading server infrastructure is that the cost & difficulty of getting set up with SSL certificates can be a major barrier for projects.

If this is the case for your project we’d like to recommend you check out Let’s Encrypt. Let’s Encrypt is a free, automated Certificate Authority that operates with support from a large number of sponsors such as Mozilla, the EFF, Chrome and Cisco.

The next most common obstacle to upgrading to SSL is that sometimes we rely on servers that are not under our direct control.

For these cases Apple have communicated that they will allow some temporary exceptions to smooth the transition, but the rules moving forward are strict:

• Most exceptions will need to be justified to Apple. This will likely lead to delays during the approval process and may end with your app being rejected.
• NSExceptionRequiresForwardSecrecy will not require a justification for now. If used, this exception will be granted automatic approval. This is likely to change in future as forward secrecy becomes more widely spread.
• NSExceptionAllowsInsecureHTTPLoads and NSExceptionMinimumTLSVersion will all require a reasonable justification for use.

Step 4: Configure ATS Exceptions (optional)

ATS Exceptions can be configured in the Toolkit via the “Configure iOS ATS” section of the request module configuration:

The fields should be self-explanatory but for more information you can read the request module documentation.

Don’t forget to re-enable ATS once you’ve configured any exceptions!

If you want to edit your app’s src/config.json file directly you may find the syntax is a little more obscure:

The format is an array of objects each with a domain and a set of one or more keys such as NSThirdPartyExceptionAllowsInsecureHTTPLoads that can be set to true for each kind of exception you want to add.

The example above corresponds to the Toolkit screenshot and it requests the following exceptions for all requests to the domain httpbin.org:

• Override ATS for HTTP requests to httpbin.org, a domain we do not control. If we did control this domain we’d have used the NSExceptionAllowsInsecureHTTPLoads key instead.
• Override the Forward Secrecy requirement for any HTTPS requests to httpbin.org.

You can find a full list of all the supported keys in Apple’s documentation.

Switch Your App To Forge v2.5

If you’ve come this far your app should be ready for testing on the iOS 10 and there are just two more steps you’ll need to take:

Step 1: Install Xcode 8

If you haven’t already got it, grab the Xcode 8 GM Seed from the Apple Developer Site and install it into your /Applications directory.

Step 2: Change your App’s Platform Version

Open your app’s src/config.json file, locate the platform_version key and set it to v2.5.1:

…and you should be ready to go!

Finally

You can keep track of further releases and known issues for this Release on the Platform Release Notes page.

If have questions or run into issues please check out the Forge v2.5 Platform Topic on the community forum.

Have fun!