Packaging for a mobile device

Before you deploy an application to a mobile device, you must package the files into an .aab or .apk file (for Android™ devices) or an .ipa file (for iOS devices).

Creating a package for a mobile platform follows the general packaging procedure, with additional planning as outlined below.

When you build the package, an .aab or .apk file (for Android devices) or an .ipa file (for iOS devices) is created. It is saved to the Distribution directory specified in the Package node. The filename is taken from the package node name. The default distribution directory is $(ProjectDir)/distbin.

Move files into a writable directory

If you have writable files that need to be updated by the app (such as database files), those files must be placed into a read-write directory on the device.

Create the user database

In addition to simply copying writable files, one of the first things your app needs to do is create the user database in a writable directory. This database may use the initial database file when creating the user database, or it may create one with a different schema for the user.

For an example, open the OfficeStoreMobile demo project, open the OrdersApp_prg.4gl intermediate file, and look for the OrdersApp_install function. In this function, the os.Path.copy method is used to copy a database file from the read-only source directory to the read-write destination directory.

Package node properties

The properties of the Package node have specific functions for mobile packages:

The ID property must conform to platform-specific standards.
- Android packages require Android application IDs. See Set the application ID (Android developer site).
- iOS packages require IDs that conform to the format of the bundle identifier for Apple apps. See CFBundleIdentifer (Apple developer site).
The Label property becomes the app name.
The Version property has platform-specific requirements.
- Android version numbers must conform to the standards for Android versioning. See Version your app (Android developer site).
- For iOS packages, the version number must be incremented each time you submit a new version to the Apple® AppStore.
The Main module property becomes the default app.
Note:
For a BAM mobile application, make sure to include the _prg suffix, for example OrdersApp_prg.
Use the Android package properties to choose colors and icons, to set permissions for the Android package, and to specify Cordova Plugins.
Use the iOS package properties to specify the launch screen, the application icon, and any Cordova Plugins.

Important:

The Package node no longer sets colors for Android appications. Instead, use Genero Browser Client theming to set colors in an application. For more information, go to Theme colors in the Genero Browser Client User Guide 4.01.

Manage your updates

When you create a new version of the app, you need to manage your app updates.

Embed a custom GBC client

To embed a custom GBC client in your mobile package, you must select and configure a Universal Rendering environment set.

Tip:

Rather than select and modify an environment sets provided during installation, we recommend you duplicate the environment set, then modify your duplicate. This preserves the original environment set and allows you to provide a name for your modified environment set that reflects its purpose.

In this environment set, you need to:

Set GBC_USER_DIR to the directory path containing your compiled GBC customizations.
Set GBC_USER to the name of the GBC customization folder. The folder must be located in the directory specified by GBC_USER_DIR.

Note:

With the Universal Rendering environment set, the values set for GBC_USER_DIR and GBC_USER are used to set the value for FGLGBCDIR, which is used when creating the mobile package.

For more detail regarding the Universal Rendering environment set, see Configure for a GUI client.

Additional considerations for Android

You need an internet connection the first time you build an Android package. During this first build, an automated process downloads and installs Gradle with all necessary extensions into a directory in your user directory. See http://www.gradle.org for more information about the Gradle project automation tool.
The packaging of a GMA application is handled under the covers by the gmabuildtool, which uses a cache. This cache is created in a temporary directory and, if not managed, can grow to a significant size. You should take care to monitor the size of this cache and manually clean out the cache files, to ensure that it does not become too large in size. For more information about the gmabuildtool and the cache it creates, see the Genero Business Development Language User Guide.
See also Troubleshooting Android packaging issues.

Additional considerations for iOS

Read about the GMIUSERDIR environment variable, to determine whether it should be set for your package.
The packaging of a GMI application is handled under the covers by the gmibuildtool. For more information about the gmibuildtool, see the Genero Business Development Language User Guide.