Trigger.io Forge v2.5 and iOS 10 Migration Guide
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:
1 2 3 4 5 6 7 8 9 |
"modules": { "calendar": { "version": "2.8", "config": { "usage_description": "We would very much like to surprise you on your birthday." } }, ... |
…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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
"launchimage": { "version": "2.10", "config": { "ios": { "wC_hC": "launchimage/1334x750.png", "wR_hC": "launchimage/1920x1080.png", "wC_hR": "launchimage/1080x1920.png", "wR_hR": "launchimage/2732x2048.png" }, "android": { "portrait": "launchimage/2048x1536.png", "landscape": "launchimage/1536x2048.png", "background-color": "#0000FF", "background-size": "cover" }, "hide-manually": true } } |
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:
1 2 3 4 5 6 7 8 9 |
"modules": { "request": { "version": "2.8", "config": { "disable_ats": true } }, ... |
…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
andNSExceptionMinimumTLSVersion
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
"request": { "version": "2.8", "config": { "disable_ats": false, "ats": [ { "domain": "httpbin.org", "NSThirdPartyExceptionAllowsInsecureHTTPLoads": true, "NSThirdPartyExceptionRequiresForwardSecrecy": true } ] } }, |
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 theNSExceptionAllowsInsecureHTTPLoads
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
:
1 2 3 4 5 6 |
{ "config_version": "4", "name": "MyApp", "platform_version": "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!