Building hybrid apps in the cloud uses the PhoneGap Build service from Adobe. Unfortunately, Adobe no longer maintains this service. PhoneGap does not allow you to create iOS 13 builds, but the Apple App Store requires builds be iOS 13 or higher. As a result, as of April 30th 2020, hybrid iOS apps built using the PhoneGap Build service are not being accepted on Apple’s App Store. To publish your iOS app in the Apple App Store, we recommend you build native iOS apps instead. For more information, see How to Build Native Apps.
Once you have finished developing a Mendix hybrid mobile application, you will want to make it available as an app for mobile platforms such as Apple iOS and Google Android. We make it possible to produce platform-specific installation packages. For more details on deploying platform-specific installation packages, see Mobile App.
The hybrid mobile app packaging process is based on Adobe PhoneGap. We have integrated the Adobe PhoneGap Build service into Mendix to provide support for automatically building the required hybrid mobile packages. Instead of worrying about technical details, you can focus on what matters most: rapidly developing an app to support your business processes.
This how-to will teach you how to do the following:
- Set up app signing keys
- Complete the app-packaging process
- Install an iOS or Android app on a mobile test device
- Upload your app to the Apple App Store or Google Play Store
Before starting this how-to, make sure you have completed the following prerequisites:
- Have a Mendix app with mobile support running in the Mendix Cloud, either as a Free App or on a licensed cloud node
- If you require an app to test with, set up the Event App from the Mendix App Store as a Free App to try out its mobile features
- Have an account for Adobe PhoneGap Build (you can create one for free here)
To publish your app in the Apple App Store, do the following:
- Register for an Apple Developer Account
- Have an iOS device (iPhone or iPad) for testing the iOS package that will be produced
- Have an iOS deployment certificate and a provisioning file for which your mobile test device is activated
- Have Apple iTunes installed on your computer for deploying the iOS package that will be produced on your mobile test device
To publish your app in the Google Play store, do the following:
- Have an Android device for testing the APK package that will be produced
3 Tutorial Video
The video below shows how to build a PhoneGap app in the cloud. After showing you how to build mobile app store packages, it explains how to find these packages in PhoneGap and add security keys to them.
How to build a PhoneGap app in the cloud
4 Starting the Packaging Process
Building hybrid apps in the cloud uses the Phonegap Build service from Adobe. Unfortunately, Adobe no longer maintains this service. As a result, as of April 30th 2020, hybrid iOS apps built through the platform or via the Phonegap Build service are not being accepted on Apple’s App Store. To address this, please follow the guide on building your hybrid iOS apps locally here.
To start the packaging process, follow these steps:
Open the Developer Portal.
Go to the project of the Mendix app that you want to publish.
Go to the Deploy > Mobile app entry in the side menu of the project.
You will be shown the Publish App for Mobile App Stores page, where you need to set up some options for your hybrid mobile app.
On the App Info tab set up the following settings for your app: a. Fill in the name that your app will have in the app stores and on the device. The Name should correspond to the name set up in your Apple certificate. b. Set the unique App Identifier for your app. The App Identifier should correspond to the ones set up in your Apple certificate. c. If your app does not employ push notifications, disable the Push Notifications permission by clearing its check box.
Select the platforms that you want to support.
Optionally, upload custom-branded app icons and splash screens under the tabs for the different platforms. You can find those tabs next to the App Info tab.
If you do not upload any images, the default Mendix-branded images that are shown will continue to be used.
- Click the green Publish for Mobile App Stores button. You will be presented with the Build Mobile App Store Packages page:
Select where you want to publish:
- For Free Apps, the only option is Sandbox
- For apps running on a licensed cloud node, you can choose from Test, Acceptance, and Production (depending on what is available on your cloud node)
- For apps using Flexible Environments you will be able to select the environment from a drop-down list of environments.
Leave the default choice of how to build the package Build Mobile App Store packages for me by sending the build configuration to Adobe PhoneGap Build selected. You can use the alternative option to manually download a PhoneGap Build package, which you can then inspect, modify, and upload manually to Adobe PhoneGap Build (for more information, see Customizing PhoneGap Build Packages). This is unnecessary in most scenarios.
Before proceeding, you must link your PhoneGap account to your Mendix account. Start the hybrid mobile app package building process by clicking Start PhoneGap Build job, which will initiate the building process:
The first time you start this process, you will need to authorize the Mendix Developer Portal to act on your behalf with the Adobe PhoneGap Build service. In PhoneGap Build, you will be presented with a dialog box asking if you want to start the redirect to Adobe PhoneGap.
a. To build for the authorization, click Authorize use of Adobe PhoneGap Build, after which you will be temporarily redirected to the website of your Adobe PhoneGap Build.
Choose Yes on the Adobe PhoneGap Build service page to allow the start of building jobs using your account. You will then be redirected back to the Mendix Developer Portal.
If you choose No, you will be redirected back to the Developer Portal and you will not be able to publish your app.
After you have been redirected back to the Mendix Developer Portal, the packaging process will continue and you will have to set up your app’s signing keys.
5 Setting Up App Signing Keys
The PhoneGap Build: Signing Key Required page asks you to go to the PhoneGap Build website and set up the app signing keys. To set up the app signing keys, follow these steps:
- Click Log in to PhoneGap Build. A new page will be opened on PhoneGap’s apps tab. Here you can see the PhoneGap Build app that was created by the Mendix Developer Portal for your app. The app is named as you defined it in the App Info in the Starting the Packaging Process section above.
- Set up the app signing key for your app in your account.
Click the avatar icon at the top-right of the page, and then click Edit account to configure how your app will build:
6 Preparing and Publishing Your App
For publishing to a specific platform, see the subsequent sections of this how-to:
7 Preparing and Publishing for iOS
Apple provides general information on publishing an iOS app in the Apple App Store. Before uploading your app, make sure to check the App Review Guidelines to make sure your app will be accepted. An Apple Developer Account is required. If you do not have one, register as an Apple Developer.
In PhoneGap Build, click your avatar icon, then click Edit account:
Click the Signing Keys tab, and under iOS, click add a key:
A dialog box will prompt you to upload a certificate file and a provisioning profile file. You can get those files from Apple. The certificate is the .p12 file, and the provisioning profile is the .mobileprovision file. For more information, see the Managing App Signing Keys Reference Guide.
Give the key a title that you can easily recognize, and upload the files.
Click the lock with the yellow background on the same row as your key and enter a passphrase. The key can now be used for builds for the period of an hour. After an hour, the passphrase needs to be entered again:
Click Apps at the top of the page to go to an overview showing your apps. Click your app’s name or logo to see the app’s details.
Select the correct key for your app. Next to the text iOS, there is a drop-down menu with the No key selected option. From the drop-down menu, select the newly uploaded key which should be listed under unlocked.
Your PhoneGap Build account is now ready and you can continue the packaging process.
7.1 Completing the Packaging Process
To complete the building process in the Mendix Developer Portal, follow these steps:
- Close your Adobe PhoneGap Build page and navigate back to your original Mendix Developer Platform page.
- Click Restart build job to restart the packaging process. a. You will see a Building Mobile App Store Packages page, which will display a Building status while PhoneGap Build is building your app. Once your app is ready, the page’s status will show Done.
- Click the Download iOS package button, and save the package (the .ipa file) to your computer.
7.2 Installing the iOS App on Your Mobile Test Device
You can now deploy your app to your mobile test device. You must use a Mac mobile test device for this step. An easy way to do this is with Apple iTunes.
To install the iOS app on your mobile test device, follow these steps:
Connect your Apple mobile test device to your computer. Both will show dialog boxes which ask you to confirm that you trust the devices. Click Continue on your device, and Trust This Computer? on your mobile device to proceed.
Open iTunes and connect your iOS mobile test device to your computer.
Select the .ipa package file that you downloaded earlier, and drag it onto your mobile test device’s Devices section on iTunes’ left menu. Drop the .ipa file there to install it on your mobile test device.
If there is an existing version, iTunes will ask if you want to replace that existing version of the app. If there is one, do so.
Your app will show up in the list of apps. Click the Install button next to your app.
Click Apply at the bottom of the screen to execute the actual installation.
The app will now be visible on your device. Open it and sign in to the app with a regular user account. You can set one up in the Mendix app in your desktop browser if you have not done so yet.
7.3 Uploading the iOS App to the App Store
- Follow Apple’s Add an app to your account tutorial to add an app entry to your account.
After adding a new app to your account, follow Apple’s View and edit app information tutorial to describe your new app entry. Consult the other pages under the left menu’s Enter app information category should they apply to your app:
Follow Apple’s Uploading builds overview to upload a build of your app to App Store Connect.
Use Apple’s Choose the build before you submit to review to select the build which you will submit to App Review.
Test your app per the TestFlight beta testing overview documentation to ensure your app works the way it should. TestFlight beta testing allows you to control which users can test your app, and then collect feedback from them.
Publish your app by following Apple’s Overview of publishing an app and the subsequent documents in the left menu’s Publish on the App Store category:
8 Preparing and Publishing for Android
If you plan on publishing an Android app, read Google’s overview of the Android app publishing process. Before submitting your app to an app store, review the launch checklist. Google provides information on publishing your app in the Google Play Store.
If you are just testing your app, you do not need to create a keystore. You can continue with the next section Enabling your Mobile Test Device for an Android Binary (APK) below.
If you want to publish your Android app, you must first complete the Android section of Managing App Signing Keys. This section explains how to generate a keystore and upload that keystore to PhoneGap Build.
8.1 Enabling your Mobile Test Device for an Android Binary (APK)
After you create your build you can download the resulting APK using a download link or a QR code. To enable APK installations:
- Open your device’s Settings.
- Open Apps and notifications, or on a Samsung Galaxy Biometrics and Security.
- Tap Install unknown apps (on certain devices you may have to tap Special access first).
- Select the browser you wish to use when downloading APK files.
- Enable the Allow from this source switch or check box.
- Tap the OK button if prompted.
8.2 Installing Your APK
To install your APK, you can either download the APK file using your mobile device’s web browser, or transfer the APK file to your Android device using a USB cord.
8.2.1 Option 1: Using Your Device’s Browser
Go to the PhoneGap install page using your mobile test device’s browser to continue installation, then follow these instructions:
- Tap the Android link to get the APK.
- Navigate to your browser’s Downloads folder, open it, and tap your downloaded app.
- On the next screen, tap the Install button to install it.
To install an APK file directly from your Android’s Download folder:
- Tap the Back button to see your list of apps.
- Tap the file manager app you will use to install the APK file.
- Tap the Allow switch or check box.
- Tap the OK button if prompted.
8.2.2 Option 2: Using a USB Cord
The second way to install your app is by connecting your device to a machine via USB. To Install an APK from your device’s file manager app this way:
- Follow the instructions on Google’s Transfer files between your computer & Android device to get the APK onto your device. Remember which folder you transfer the APK into.
- Open your phone’s file manager, navigate to the folder you transferred your APK to, then tap the APK file to open it.
- Tap the Install button.
- Tap the Done button when prompted. You should now be able to access your installed app via your App Drawer, as well as by tapping the Open button after the installation completes.
8.3 Testing Your App
Using your new app, ensure all pages, buttons, and functionality work the way you intended them to. You can test your app using automatic software, such as BrowserStack, or test your app manually.
8.4 Upload to Play Console
Upload your Mendix app to the Play Console by following the instructions on Google’s Upload your app to the Play Console site. Before uploading to the Play Console you will have to complete the signup steps of signing-in with your Google account, accepting the developer agreement, paying the registration fee, and completing your account details. Once you have satisfied those requirements, you can upload your app to the Play Console.
8.5 Create, Review, and Roll Out a Release
Follow the steps in Google’s Prepare & roll out releases to create, prepare, review, and roll out your app release. You can also consult Google’s Run apps on a hardware device for detailed instructions on testing your app using a physical Android device instead of an emulator.