Debug a Hybrid Mobile App

Last modified: January 15, 2024

1 Introduction

Mendix has great tools for debugging web applications, including the offline and online debugger, but many people do not know that these tools can also be used to debug and test mobile applications.

This how-to teaches you how to do the following:

  • Build and run a hybrid Mendix mobile app that connects to your local development machine
  • Debug the mobile app using Mendix debugging tools, Chrome DevTools and the Safari Web Inspector

2 Prerequisites

Before starting this how-to, make sure you have completed the following prerequisites:

  • Ensure that you have a network utilities tool on your mobile device (I use PingTools on Android, and NetworkPing Lite on iOS) in order to ensure connectivity between your device and your computer
  • Acquire a paid Apple Developer Membership—see Apple Membership for more details

3 Android and macOS

This is perhaps the easiest combination of a mobile target platform and a development environment to configure.

3.1 macOS Configuration

Since Mendix Studio Pro only runs on Windows, you need to make sure that your virtual (Windows) machine can be accessed by the outside world. To do that, the network setting must be shared between the virtual machine and your Mac, and the appropriate ports forwarded. Follow these steps to configure your development environment with Parallels:

  1. Open the Parallels Configure dialog:

    mac-1
  2. Go to the Hardware tab:

    mac-1b
  3. Make sure that the Source for Network 1 is set to Shared Network. Click the lock to make changes.

  4. Open the Parallels Preferences dialog window:

    mac-3
  5. Go to the Network tab.

  6. Make sure that the Connect Mac to this network option is checked:

    mac-3b
  7. Click + button at the bottom of the page to add a new Port Forwarding Rule with the following settings:

    • Protocol: TCP
    • Source Port: 8080
    • Forward to: Win10
    • Destination Port: 8080
    mac-4
  8. Add another rule, this time forwarding port 8090.

  9. Start the Mendix app locally, and verify that your mobile device can ping your development machine.

  10. Find the local IP of your development machine on your network by going to settings > network:

    mac-6
  11. Verify that your device can ping this address:

    win-2

3.2 PhoneGap Configuration

You can use PhoneGap Build to build the native mobile application and tell it to initialize based on this new URL, rather than the default. Follow these steps to download a package, update it, and upload it to PhoneGap Build:

  1. Go to home.mendix.com and open your app.

  2. Go to the Mobile App page.

  3. Configure this page as you normally would and then click Publish for Mobile App Stores:

    phonegap-1
  4. Select Do it Yourself and then click Download Customizable Package:

    phonegap-3
  5. Extract the downloaded package and then navigate to the /dist/ folder:

    phonegap-4
  6. Extract the contents of the phonegap.zip file and open the www/settings.json file:

    phonegap-5
  7. Change the url property to the IP address of your local machine, with the port 8080.

    1
    2
    3
    4
    5
    6
    7
    
    {
      "url": "http://10.140.149.92:8080",
      "hybridTabletProfile": "",
      "hybridPhoneProfile":  "",
      "enableOffline": false,
      "requirePin": false
    }
    
  8. Save your changes and zip the unzipped phonegap.zip files you just extracted:

    phonegap-7
  9. Upload the new zip file to a new app on PhoneGap Build:

    phonegap-8
  10. When your app has finished building in the cloud, download it and run it to connect to your Mendix app running on your local machine.

3.3 Android Configuration

  1. Enable the developer options on your Android device. See Configure On-Device Developer Options for more information.

  2. Connect your device to your development machine and when the popup window appears on your mobile device to allow USB debugging, choose Allow:

    android-2
  3. Open the Chrome browser.

  4. Open the Chrome Developer Tools (F12).

  5. Click Customize and control DevTools ( ) and select More tools > Remote devices:

    android-3
  6. Select your device from the list:

    android-4
  7. Inspect the tab from your mobile device to preview the view from your device on-screen and to gain access to the Chrome web inspector and the rest of the Developer Tools.

You can now take advantage of all the debugging tools you know and love with Mendix, including offline breakpoints, quick updates/refreshes, and the Chrome Developer Tools.

4 iOS and macOS

4.1 Apple Developer Configuration

In order to build (and debug) a Mendix iOS app, you need to ensure that you have the right setup in your Apple Developer Account. You will need a Developer Provisioning Profile that includes your device ID and a Signing Certificate. If you already have an iOS Development provisioning profile, you can continue with 5.2 PhoneGap Configuration. Follow these steps to set up an iOS provisioning profile:

  1. Go to developer.apple.com and sign in to your account.

  2. Click Certificates, IDs & Profiles in the left-side navigation.

  3. Click the + button to create a new certificate.

  4. Select iOS Development and click Continue:

    apple-5
  5. Follow the instructions to create a Certificate Signing Request (CSR) and click Continue:

    apple-6
  6. Upload your new CSR and click Continue:

    apple-7
  7. Download your new certificate and click Done:

    apple-8
  8. On your Mac, open Keychain Access and select Import Items… from the File menu:

    apple-9
  9. Select your new certificate:

    apple-10
  10. Right-click the certificate in the list of certificates and select Export:

    apple-11
  11. Save this as a .p12 file, and remember this for later. You will need this to build your Phonegap application:

    apple-12
  12. Return to the Certificates, Identifiers & Profiles page.

  13. Navigate to the App IDs page, located under Identifiers.

  14. Click the + button to create a new App ID.

  15. Enter an App ID Description and Explicit App ID and select the necessary Apple services your app will need, then click Continue:

    apple-15
  16. Click Register, then Done.

  17. Connect your iOS device and open iTunes.

  18. Navigate to your device overview in iTunes, and click where it lists the serial number to reveal the UDID:

    apple-18
  19. When you see the UDID, right-click it and select Copy:

    apple-19
  20. Return to the Certificates, Identifiers & Profiles page and navigate to the All page under Devices.

  21. Click the + button to add a new device.

  22. Enter a name for the device and paste the UDID:

    apple-21
  23. Navigate to All under Provisioning Profiles.

  24. Click the + button to create a new Provisioning Profile.

  25. Select iOS App Development and click Continue:

    apple-23
  26. Select your new App ID from the drop-down and click Continue:

    apple-24
  27. Select your new Certificate and click Continue:

    apple-25
  28. Select the devices you want to test your app and click Continue:

    apple-26
  29. Give you new Provisioning Profile a name and click Continue:

    apple-27
  30. Download your Provisioning Profile (you will need this for Phonegap).

4.2 Phonegap Configuration

You can use PhoneGap Build to build the native mobile application and tell it to initialize based on this new URL, rather than the default. Follow these steps to change the PhoneGap Build

  1. Go to home.mendix.com and open your app.

  2. Navigate to the Mobile App page, listed under Deploy.

  3. Configure this page as you normally would and click Publish for Mobile App Stores:

    phonegap-1
  4. Select Do it Yourself and click Download Customizable Package:

    phonegap-3
  5. Unzip the downloaded package and navigate to the /dist/phonegap.zip file:

    phonegap-4
  6. Extract the contents of this file and find www/settings.json:

    phonegap-5
  7. Change the url property to the IP address of your local machine, with the port 8080.

    1
    2
    3
    4
    5
    6
    7
    
    {
      "url": "http://10.140.149.92:8080",
      "hybridTabletProfile": "",
      "hybridPhoneProfile":  "",
      "enableOffline": false,
      "requirePin": false
    }
    
  8. Save your changes and rezip the phonegap directory in /dist/:

    phonegap-7
  9. Upload the new zip file to a new app on Phonegap Build:

    phonegap-8
  10. Navigate to Edit Account from the account menu:

    phonegap-9
  11. On the Signing Keys tab, click Add a Key under iOS:

    phonegap-10
  12. Choose your .p12 certificate (from Step 12 in the Apple Developer Configuration) section and your new provisioning profile:

    phonegap-11
  13. Click the lock to temporarily unlock your key:

    phonegap-12
  14. Return to the app online and choose your new key from the drop-down. This will trigger a new build of your app:

    phonegap-13
  15. When your app finishes building in the cloud, scan the QR code to download the app and run it on your iOS device.

4.3 iOS Configuration

  1. Go to Settings > Safari on your iOS device:

    ios-1
  2. Select Advanced:

    ios-2
  3. Ensure that Web Inspector is turned on:

    ios-3
  4. Ensure that your iPhone can ping your development machine (if you have not already):

    ios-4
  5. Return to the running Mendix app on your iOS device.

  6. Open Safari on your Mac.

  7. If you do not have the Develop option on your menu bar, open Safari > Preferences:

    ios-6
  8. On the Advanced tab, ensure that Show Develop Menu in menu bar is checked:

    ios-7
  9. From the Develop menu, select your device and running application:

    ios-8
  10. This will bring up the Safari Web Inspector for your device.

5 Android + Windows

5.1 Windows Configuration

Follow these steps to test your computer’s connection to your device:

  1. Open the command prompt and type ipconfig /all and find the IPv4 address of your wireless adapter:

    win-1
  2. Verify that your device can ping this address:

    win-2

5.2 PhoneGap Configuration

You can use PhoneGap Build to build the native mobile application and tell it to intialize based on this new URL, rather than the default. Follow these steps to create a new configuration:

  1. Go to home.mendix.com and open your app.

  2. Navigate to the Mobile App page under Deploy.

  3. Configure this page as you normally would and then choose Publish for Mobile App Stores:

    phonegap-1
  4. Select Do it Yourself and then click Download Customizable Package:

    phonegap-3
  5. Unzip the downloaded package and navigate to the /dist/phonegap.zip file:

    phonegap-4
  6. Extract the contents of this file and find www/settings.json:

    phonegap-5
  7. Change the url property to the IP address of your local machine, with the port 8080.

    1
    2
    3
    4
    5
    6
    7
    
    {
      "url": "http://10.140.149.92:8080",
      "hybridTabletProfile": "",
      "hybridPhoneProfile":  "",
      "enableOffline": false,
      "requirePin": false
    }
    
  8. Save your changes and rezip the phonegap/ directory in /dist/:

    phonegap-7
  9. Upload the new zip file to a new app on Phonegap Build:

    phonegap-8
  10. When your app finished building in the cloud, download the app and run it to connect to your Mendix app running on your local machine!

5.3 Android Configuration

  1. Enable the developer options on your Android device. See Configure On-Device Developer Options for more information.

  2. Connect your device to your development machine and when the popup appears on your mobile device to allow USB debugging, choose Allow:

    android-2
  3. Open the Chrome browser.

  4. Open the Chrome Developer Tools (F12).

  5. Click Customize and control DevTools ( ) and select More tools > Remote devices:

    android-3
  6. Select your device from the list:

    android-4
  7. Inspect the tab from your mobile device to preview the view from your device on-screen and to gain access to the Chrome web inspector and the rest of the Developer Tools.

You can now take advantage of all the debugging tools you know and love with Mendix, including offline breakpoints, quick updates/refreshes, and the Chrome Developer Tools.

For more help with Android remote debugging, check out Get Started with Remote Debugging Android Devices.

6 Read More