7 Build Mobile Applications

Before you build a mobile application, you define a build configuration that describes how to build the mobile application for the platform where you install the application (Android and/or iOS). If you want to build a Progressive Web App (PWA) from your mobile application, you need to enable the PWA option in the mobile application's Settings page.

Once you have defined the build configuration for the platform, or enabled the PWA option, and reviewed the property values in the mobile application’s settings, you build the mobile application for the corresponding platform. At the end of the build process, VB Studio generates QR codes and links to installation files. You or other users scan the QR code to install the mobile application or, alternatively, you download the installation file from the provided link and install it on the device.

VB Studio provides ready-to-use image files for the Android and iOS platforms that render the application launcher icon and splash screen for the mobile application on the device. You can replace these ready-to-use image files with custom image files that conform to the look and feel you want your mobile application to render. Similarly, VB Studio provides ready-use permission strings for the mobile applications that it builds for the iOS platform. You can also replace these permission strings with custom permission strings that you define.

Configure Mobile Application Settings

After creating your mobile application, review the settings for your application to verify that it has appropriate values for properties like App Name and Lock Portrait Mode.

  1. Click the Mobile Applications tab.
  2. Click the <app name> node and click the Settings icon (Settings icon).
    The General Settings tab is displayed.
  3. In the Application Settings tab, select the main or starting page for your mobile app from the Default Page list. This page is displayed when you open the app.
  4. Select a value to specify the theme, if any, to use for the mobile app.
  5. In the App Name field, enter the app name that is to be displayed when the app is installed on a mobile device.
  6. Enter the name of the vendor who originated the application in the Vendor Name field.
  7. Enter text that describes the application in the Description field.
  8. Enter the URL scheme for the app in the URL Scheme field.
  9. Specify the package name for the app in the Package Name/Bundle ID Default field.
    To avoid naming conflicts, Android and iOS use reverse package names, such as com.company.application.
  10. Clear the Lock Portrait Mode checkbox if you want the mobile application to render in both Landscape and Portrait mode on the user's device. By default, the application renders in Portrait mode only.
  11. Select the Support iPad Deployment checkbox if you want to deploy the mobile application to iPad.

Define a Build Configuration for the Android Platform

Define one or more build configurations for the Android platform to test and deploy your mobile applications.

Before you define a build configuration, make sure you have access to a keystore and its access credentials. The build configuration that you define uses the keystore to sign the mobile application when it builds it. For information about creating a keystore and using it to sign an app for the Android platform, see Sign Your App in Android Studio’s documentation.

  1. Click the Mobile Applications tab.
  2. Click the <app name> node and click the Settings icon (Settings icon).
    The General Settings tab is displayed.
  3. Select the Build Configurations tab and click Android in the New Configuration list.
    The Create New Android Build Configuration dialog box is displayed.
  4. Enter a name for the configuration in the Configuration Name field.
  5. Select the build type from the Build Type list. Possible options include Debug or Release.
    Select Debug to build a mobile application that is in development and you want to share it with testers. Select Release when you have completed development of your mobile application and want to publish it for download by end users. In VB Studio, if you deploy a visual application to production that includes a mobile application, ensure that you use Release as the build type.
  6. In the Search Profile input field, search for an application profile to assign to the build configuration. You can use the default application profile (Base configuration) that VB Studio provides or you can create your own application profile.
  7. Enter a unique ID for the application in the App ID field. Each application deployed to an Android device has a unique ID, one that cannot start with a numeric value or contain spaces.
  8. Specify the release version number for the application in the Version Name field. This is the release version of the application code that is displayed to the user. For example, enter 2.0 if this is the second version of your application. The value you enter appears in application information dialogs when you deploy the application to a device.
  9. Enter an integer value that represents the version of the application code in the Version Code field. This version code is checked programmatically by other applications for upgrades or downgrades. The minimum and default value is 1. You can select any value and increment it by 1 for each successive release.
  10. Drag and drop, or browse to and retrieve, the directory of the keystore containing the private key used for signing the application for distribution in the Keystore field.
  11. Enter the password for the keystore in the Keystore Password field. This password allows access to the physical file.
  12. Enter an alias for the key in the Key Alias field. This is the value set for the keytool's -alias argument. Only the first eight characters of the alias are used.
  13. Enter the password for the key in the Key Password field. This password allows access to the key (identified by the alias) within the keystore.
  14. Optionally, review the custom application template that is automatically selected. The field is displayed only if a custom application template is defined for the selected build type. You can define one application build template each for the Debug and Release build types.
  15. Click Save Configuration.
The new build configuration is displayed on the Build Configurations page.

Define a Build Configuration for the iOS Platform

Define one or more build configurations for the iOS platform to test and deploy your mobile applications.

Before you define a build configuration, you must create a provisioning profile. To create a provisioning profile, you require membership of the iOS Developer Program or the iOS Developer Enterprise Program. A provisioning profile associates development certificates, devices, and an application ID. The build configuration you create uses the provisioning profile that you specify to build the mobile application for the iOS platform. For more information about iOS developer programs and provisioning profiles, review the App Distribution Guide available through the iOS Developer Library.
  1. Click the Mobile Applications tab.
  2. Click the <app name> node and click the Settings icon (Settings icon).
    The General Settings tab is displayed.
  3. Select the Build Configurations tab and click iOS in the New Configuration list.
    The Create New iOS Build Configuration dialog box is displayed.
  4. Enter a name for the configuration in the Configuration Name field.
  5. Select the build type from the Build Type list. Possible options include Release and Debug.  
    Select Debug to build a mobile application that is in development and you want to share it with testers. Select Release when you have completed development of your mobile application and want to publish it for download by end users. In VB Studio, if you deploy a visual application to production that includes a mobile application, ensure that you use Release as the build type.
  6. In the Search Profile input field, search for an application profile to assign to the build configuration. You can use the default application profile (Base configuration) that VB Studio provides or you can create your own application profile.
  7. Enter a bundle ID in the Bundle ID field or accept the default value generated by VB Studio.
    The bundle ID must be unique for each application installed on an iOS device. The application ID must adhere to the format set in the iOS Provisioning Portal and cannot contain any spaces. For more information, see the documentation available through the iOS Developer Library.
  8. Specify the version name in the Bundle Version Name field.
    The release version number for the application. This version number is displayed to the end users and identifies a released iteration of the application. It is a string made up of three non-negative and period-separated integers, such as 3.1.2. The string should only contain numeric (0-9) and period (.) characters.
  9. Enter the version in the Bundle Version field.
    The version you enter corresponds to the build number that identifies an iteration (released or unreleased) of the application and must be incremented each time the application is uploaded to the Apple App Store. The build version is typically a string made up of three non-negative and period-separated integers, such as 3.1.2. The string should only contain numeric (0-9) and period (.) characters.
    • The first number represents the most recent major release and must be greater than zero. The integer is limited to a maximum length of four digits.

    • The second number represents the most recent significant revision and is limited to a maximum length of two digits.

    • The third number represents the most recent minor bug fix and is limited to a maximum length of two digits. If the value of the third number is 0, you can omit it and the second period.

  10. Drag and drop, or browse to and retrieve a certificate in the Certificate field.
    Ensure you use the certificate associated with the provisioning profile you intend to use (Step 11) for this build configuration. The certificate file must be a P12 file (.CER format is not supported), for example, ent2_2018.p12. The iOS Development Certificate electronically associates a developer’s identity with a public key and private key. The certificate identifies you as an iOS developer and enables the signing of the application for deployment. In the iOS operating environment, all certificates are managed by the Keychain Access app.
  11. In the Certificate Password field, enter the certificate password that was set to protect the provisioning profile certificate when it was exported from the Keychain Access app.
  12. Drag and drop, or browse to and specify the location of the provisioning profile in the Provisioning Profile field.
  13. In the Signing Identity field, enter the name of the developer or distribution certificate that identifies the originator of the code (such as a developer or a company). Enter the entire name as it appears in the Common Name column of the Keychain Access app.
    You use a signing identity to code sign your application. A certificate and its public key are stored in the Member Center, and the corresponding signing identity (the certificate with its public and private key) is stored in your keychain. You will not be able to code sign without this private key. Here is how to identify the value to provide in the Signing Identity field.
    Description of sign_iden_ios-png.png follows
    Description of the illustration sign_iden_ios-png.png
  14. Optionally, review the custom application template that is automatically selected. The field is displayed only if a custom application template is defined for the selected build type. You can define one application build template each for the Debug and Release build types.
  15. Click Save Configuration.
The new build configuration is displayed on the Build Configurations page.

Provide Custom Permission Strings for Mobile Applications on iOS

Mobile applications on iOS require usage descriptions (permission strings) if the application uses hardware capabilities, such as the device camera, that allow it to access end user data.

The iOS device displays these permission strings in the system dialog that requests an end user to allow access to the hardware capability and/or potentially sensitive user data, as in the following example, where the "This applications allows the user to upload photos from their photo library" permission string appears in the dialog when the application requests access to the photo library.

Description of usage_description.png follows
Description of the illustration usage_description.png

VB Studio provides permission strings for each mobile application that it builds for iOS. Mobile applications for Android do not use these permission strings. You can provide alternative permission strings to those provided by VB Studio by uploading a ZIP file that contains the permission strings you want your mobile application to use. Upload the ZIP file through the dialog that is exposed in the Resources section of the mobile application’s Settings page. Download the sample from the Permission Strings Sample link to use as a reference when creating your ZIP file with the permission strings you want to use. The downloaded sample ZIP file contains an ios_permissions.properties file with a list of the permission strings that you can modify, such as the following:

NSCameraUsageDescription=The camera may be used to take pictures that may be uploaded to a server.

Replace the string to the right of = with the permission string you want to use and upload a ZIP file containing the modified ios_permissions.properties file. Irrespective of the name that you give to the ZIP file that you upload, VB Studio renames it to iosPermissionStrings.zip.

Description of uploaded-permission.png follows
Description of the illustration uploaded-permission.png

For information about the Apple Cocoa keys, such as NSCameraUsageDescription, see Apple’s documentation.

Build a Mobile Application

Build the mobile application to generate a QR code and installation file for your application.

Before you build your mobile application, make sure you:
  1. Open the mobile application that you want to build.
  2. Click the Preview icon (Run icon) to run the app on a new tab in the browser.
    The mobile application is displayed in the browser. If your application is configured to run as PWA, both the Native app and PWA tabs are displayed.

    Build my App Screen

  3. Click the Build my App button in the Native app or PWA tab to build a native or PWA app, respectively.
  4. In the Share Visual Application dialog, click Share.
    VB Studio builds the app(s) in the background. Once it completes, it closes the Share Visual Application dialog.
  5. Return to the VB Studio Designer browser tab and, in the visual application workspace toolbar, click the Options menu and click Open Shared Application.
    Open Shared Application Menu Option
    VB Studio opens a new browser tab where a Native app tab appears if you created a build configuration for Android or iOS and a PWA tab appears if you configured your mobile application to build a PWA. Each tab displays a QR code and a link. In the Native app tab, the QR code and link download the installation file (an .APK file for Android and an .IPA file for iOS) to install the mobile application on a device. In the PWA tab, the QR code and the link open the PWA app in your browser.

    Download Links and QR Codes for Mobile Applications

Enable Progressive Web App Support from Mobile Applications

Mobile applications that you develop in VB Studio can be distributed as Progressive Web Apps (PWA) if you enable PWA support for the application.

When a mobile app with PWA support enabled is deployed using VB Studio, the application runs as a web app and not as a native mobile app. A PWA app created in VB Studio:
  • Allows you to install the application from the browser window and add the application to the Home screen

    As a developer, you don’t need to publish the app to an app store. Instead, you can distribute a URL which prompts the user with the Add <PWAappName> to Home screen message (in Chrome on Android).

  • Runs on your device like a native app

    Similar to a native app, no address bar is displayed when a PWA app runs.

  • Offers the user experience of a native app

    PWA apps deliver user experiences through progressive enhancement. This refers to the ability to gradually add more features to a PWA app to make it closer to a native app (as browser support becomes available). For more information on PWAs, see the documentation.

  • Works offline similar to a native app

    If you implement data caching using the offline toolkit, PWA apps work offline similar to native apps.

Here is what a PWA app looks like when running in the browser.


Description of mob_pwa_run_browser-png.png follows
Description of the illustration mob_pwa_run_browser-png.png

Here is what the same PWA app looks like when running on a device.


Description of mob_pwa_run_app-png.png follows
Description of the illustration mob_pwa_run_app-png.png

When developing PWA apps, select the Oracle Cloud option in the Authentication Mechanism list in the Security tab for the mobile application.
  1. Click the Mobile Applications tab.
  2. Click the <app name> node and click the Settings icon (Settings icon).
    The General Settings tab is displayed.
  3. Select the PWA tab.
  4. Click Enable Progressive Web App (PWA).
    The Manifest Settings, Resources, and Advanced File Caching panes are displayed.
  5. Review and edit, if needed, the information displayed in the Manifest Settings pane.
    These settings are included in the web manifest file (a JSON configuration file) that contains information about your application. When an application is configured as PWA, a Web Manifest is added to the application with content required by PWA. For more information on this file, review this page.
    1. Specify the Application Name.
      The specified name appears on the dialog that displays prompts you to install the application.
    2. Review the short name of the application.
      If both application name and short name are specified, the short name is used on the Home screen (below the app icon), launcher, and other places where space is limited.
    3. Change the background color and theme color, if needed, by clicking the currently selected color and choosing a new color in the color picker or by entering a RGB value in the text field.
  6. Customize the splash screen and icons to use for your app in the Resources pane.
    By default, Oracle-provided images are used for your app. Replace these with images to use splash screen and icons that conform to your brand. Upload an application image archive either by dragging it or by using the Open dialog box.
  7. Specify the files to cache on the user’s device in the Advanced File Caching pane.
    By default, when launched for the first time, the PWA app caches all flows and pages on the user’s device. Use this pane to narrow down the required resources to be stored in the browser cache.
After you successfully build your PWA enabled mobile app, scan the generated QR Code for the PWA app from a QR Code scanner or camera app installed on your Android device.
Click the Launch in Browser link to open the PWA in the browser. After you launch the PWA application in a browser on a mobile device, you can add it to the Home screen.
  • On the iOS platform, select the Add to Home Screen option.

    Description of mob_pwa_add_to_home-png.png follows
    Description of the illustration mob_pwa_add_to_home-png.png

  • On the Android platform, when PWA applications are deployed on Android, a new install application dialog is displayed to allow users to install the application on the Home screen. The dialog displays when the application receives the new vbBeforeAppInstallPrompt lifecycle event.

    When you enable PWA for an application, a sample implementation is added to the application start page for the UI and event handling. We recommend that you customize the UI and handling of the vbBeforeAppInstallPrompt event to meet your needs.

Guidelines for Using PWA Support

Here are a few things to consider when using PWA support for your applications.

  • At present, you can only enable mobile applications that you created in VB Studio as PWAs.
  • Currently, we support the Chrome browser for Android and the Safari browser on iOS. We recommend that you use the latest available browser versions. For information on supported browser versions, review this page.
  • Here are few limitations for PWA apps running on the iOS platform. These issues may be resolved in future iOS releases.
    • Install the PWA app by using the share icon (because the Add <PWAappName> to Home screen message is not displayed).
    • PWA app state is not saved between sessions. If a user exits a PWA, the app is restarted when the user returns.
    • Navigation between screens in an app is possible only by using the built-in navigation. This is because Apple devices do not have a Back button.
    • Inactive apps appear as a white screen (no splash screen support) in the task manager.
    • Service worker cache size is limited to 50 MiB per partition.
    • Caches for unused apps are purged frequently.
    • Web manifest is not supported on Safari.
    • Orientation lock not supported.
  • Periodically delete service workers and clear cache when developing PWAs. When you repeatedly stage new versions of a PWA (in the iterative development cycle), you might run into issues with Chrome DevTools if multiple service workers are present. Here are high-level steps to do this:
    1. Click Cmd+Option+I (on Macintosh) or Ctrl+Shift+I (on Windows) to open the Chrome DevTools.
    2. Switch to the Application tab.
    3. Click Clear Storage in the left menu.
    4. Click Clear Site Data to clear the cache and unregister service workers.

Change the Splash Screen and Icons Used by a Mobile Application

VB Studio provides images that your mobile application uses to render a splash screen and app launcher icon when the application runs on the Android and iOS platforms. Replace the Oracle-provided images with your own images so that your mobile application uses a splash screen and icons that conform to your brand.

To replace the Oracle-provided images that your mobile application uses by default, you upload an application image archive through the dialog that is exposed in the Resources section of the mobile application’s Settings page, as shown in the following image.

Description of vbcs-resources.png follows
Description of the illustration vbcs-resources.png

VB Studio also provides sample application image archive files that you can download to review and determine what type of images you need to provide in the archive that you upload to VB Studio to replace the default images used by your mobile application. Each sample provides a complete list of the images that you need to upload to replace the default images provided by Oracle. The file names and, in the case of the Android sample, the directory names describe the purpose and type of image. In the iOS sample, the use of ipad in a file name indicates that the image file is intended for use on iPad devices while iTunesArtwork.png indicates that the image file is used to render the artwork for the mobile application’s entry in the Apple App Store.

The Android sample includes more images so that icons are provided to display properly on Android-powered devices of different sizes and resolutions that require low, medium, high, extra-high, extra-extra-high density, and extra-extra-extra-high density versions of the same images. The name of each directory and image file within the downloaded sample indicates its purpose. For example, the drawable-land-xxhdpi-v4 directory contains images for Landscape mode with a requirement for extra-extra-high density resolution. Similarly, the drawable-port-xxhdpi-v4 directory provides images for when the app is in Portrait mode. The 9 within file names, such as screen.9.png indicates that the image is a NinePatch image that Android resizes to accommodate the contents of a view, as discussed in Android’s documentation.

The archive that you upload should have the same number and type of images to those provided in the Android and iOS samples that you can download from the respective links in the Resources section. If, for example, you upload an application image archive for iOS, ensure that it includes an alternative image for each of the images listed in the iOS sample, as in the following two examples, that all images reside within the root directory of the zip file that you upload, and that the image you use for the splash screen is an Xcode storyboard.

Default@2x~ipad~anyany.png
...
iTunesArtwork.png

Also, for iOS, ensure that you do not use the Compress option on your Mac when you create the application image archive. Creating an archive with the Compress option results in an archive with an invalid structure that VB Studio will reject. Instead, you should do the following:

  1. From the command prompt, navigate to the directory that contains the custom images you want to include in the application image archive.
  2. Run the following command to create an application image archive with the correct structure.

    zip -r ../<your zip file name>.zip

Refer to the Android and iOS documentation for guidelines on creating icons and splash screens. Apple, for example, provides guidelines for the splash screen (launch screen) and the app icon.

Irrespective of the name that you give to the archive file that you upload, VB Studio renames it to iOSResourcesImages.zip in the case of iOS and AndroidResourcesImages.zip in the case of Android.