Trigger.io Forge v2.7 Migration Guide

header-image

Trigger.io Forge v2.7 Migration Guide


This article provides information to assist users in migrating Trigger.IO Forge apps from v2.6.x of the platform to v2.7.x.

Introduction

If your application is currently built against v2.6.x of the Forge platform it is important that you migrate to v2.7.x so that your application will continue to run on the latest Android “Pie” and iOS 12 releases.

There is in-depth information below but the major changes you need to be aware of are:

  1. The API’s for our topbar and display module have been overhauled in order to consolidate all statusbar-specific API methods and configuration keys into the forge.display namespace.
  2. The API’s for Camera and Microphone capture have been moved out of the file module and into the capture module.
  3. Support for Android Adaptive Icons.
  4. Support for Android Display Cutouts.
  5. Our httpd module now features SSL support.
  6. Modules that need to be updated to the latest versions are:
    • display
    • file
    • capture
    • httpd
    • icons
    • tabbar
    • tabs
    • topbar
    • permissions
    • geolocation
    • contact
    • calendar
    • parse

The full changelog for this release can be found in the Release Notes.

Let’s take a detailed look at the steps needed to update your app for Forge Platform v2.7.

Step 1: update to 2.7.1

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:

calendar

  • update to "version": "2.9"

capture

  • Add the capture module to your project if you are using the file module to capture photos or video.

contact

  • update to "version": "2.12"

display

  • Update to "version": "2.11"
  • Update for new config & API’s

file

  • Update to "version": "2.23"
  • Update API’s if you are using the file module to capture photos or video.

geolocation

  • update to "version": "2.8"

httpd

  • Update to "version": "0.9"
  • It’s no longer necessary to use forge.httpd.normalize() if you are using the httpd module.

icons

  • Update to "version": "2.9"
  • Add adaptive icons for Android

tabbar

  • Update to "version": "2.7"

tabs

  • Update to "version": "2.23"

topbar

  • Update to "version": "2.15"

parse

  • update to "version": "2.19"

permissions

  • update to "version": "2.0"

Step 3: Update topbar and display configurations and API usage

We’ve consolidated all configuration and API’s related to app native status bar elements into the display module.

Migrate configuration: display and topbar

All app native status bar configuration can now be done via the display module.

The new format looks like this:

For example, if you previously set the status bar style via the topbar module:

…you would move the configuration to display.config.statusbar.ios.style with a value of light_content.

Migrate API usage: forge.topbar.setStatusBarStyle()

The forge.topbar.setStatusBarStyle() API method has been moved to forge.display.setStatusBarStyle() and the argument has been changed to one of default or light_content.

So, for example if you had:

…you would rewrite it as:

Migrate API usage: forge.file.getImage() and forge.file.getVideo()

Apple are tightening their review criteria to reject apps that request device permissions which are not directly related to the functionality of an app.

Not everyone using the file module needs access to the device camera and microphone so this has made it necessary for us to move those functions to a new module called capture.

If you are currently using the forge.file.getImage() and forge.file.getVideo() API’s to capture new photos or videos you will therefore need to migrate to the new capture module.

Luckily this is as easy as:

  1. add the capture module to your app
  2. rename all usages of forge.file.getImage( ... ) to forge.capture.getImage( ... ).
  3. rename all usages of forge.file.getVideo( ... ) to forge.capture.getVideo( ... ).

Optional: Add adaptive icons for Android

Adaptive icons are not strictly compulsory as Android will still use the legacy icons:

The icon on the left is an example of how legacy icons will be rendered on a device with adaptive icon display support whereas the icon on the right shows what an adaptive icon would look like.

The primary difference between the two icon formats is that adaptive icons include a “safe zone” around the icon image which allows the device to crop the image to any custom mask shapes in use by the device.

For more information on using adaptive icons please see the icons module documentation.

Optional: Configure display cutout behavior for Android

To accommodate the rounded corners and display cutouts that are quickly becoming pervasive in the smartphone market Android “Pie” has added three new window layout modes to control how your app content is displayed on devices with non-uniform displays.

To set the particular mode used by your app you will need to edit your app’s src/config.json file and add a configuration entry for core.android.adjust_content_insets as follows:

Where value can be one of:

always

always: Your app will be automatically adjusted to always lie within the “safe” area of the device and will never extend into any of the cutout areas.

short_edges

short_edges: Content renders into the cutout area while in portrait mode, but content is letterboxed while in landscape mode. It is your responsibility to ensure that your app does not render content over any of the cutout
areas.

never

never: Your app content will extend into the cutout area on the short edge of the display in both portrait and landscape, regardless of whether the system bars or hidden or visible. It is your responsibility to ensure that
your app does not render content over any of the cutout areas.

Optional: Adjust your app layout to account for display cutouts

If you are using one of never or short_edges for the adjust_content_insets mode you will need to know the dimensions of the cutout area so you can adjust your layout accordingly.

There are currently two methods available to do this:

The first is to use the special safe-area-inset-* CSS environment variable being rolled out in the newest versions of the Chrome WebView. For more information see the Chrome 69 Beta: CSS tricks, and more blog post and scroll down to the “Display cutouts” section.

If the CSS method does not work for you, you can also use the forge.layout.getSafeAreaInsets(success, error) API call to do something along the following lines during your app’s startup:

Optional: Configure httpd for SSL

Some apps hosting complex content (e.g. iframes containing content served via https) may run afoul of WebView mixed content security policies.

To solve this problem we now support the configuration of a SSL certificate for the httpd module that will allow you to serve your app content via https://.

What you will need to do:

  1. Generate a self-signed SSL certificate for localhost. The letsyncrypt.org website has a nice overview

  2. Convert your SSL certificate to PKCS #12 (.p12) format format and set a password when prompted:

  3. Copy your localhost.p12 certificate file to your app’s src/ directory.

  4. Edit your app’s src/config.json file and edit the httpd module configuration:

Problems?

Please don’t hesitate to join us on the Forge 2.7 Community Forum Topic if you have any questions around the update process or run into any difficulties!