Setting Up your Local Development Environment

Supported Environments

In order to perform local development, you will need to have set up a local development environment or IDE. Mobile Services supports mobile app development across iOS Native, Android Native, Cordova and Xamarin.

You can only use the AeroGear Xamarin SDK to create iOS and Android Apps.

  • Cordova

  • Android

  • iOS

  • Xamarin

You need the following installed on your machine:

For information on how to set up a local Cordova development environment, see the Cordova documentation.

You need the following installed on your machine:

  • Android SDK or Android Studio from Google

  • (Recommended) The latest version of OpenJDK

For information on how to set up a local Android development environment, see the Android Studio documentation.

You need the following installed on your machine:

The AeroGear SDK for iOS is available using the CocoaPods package manager. If you have not installed CocoaPods, install it by running the command:

$ gem install cocoapods

For information on how to set up a local iOS development environment, see the Swift documentation.

You need the following installed on your system:

  • Visual Studio Tools for Xamarin from Microsoft

  • (Optional) The latest version of OpenJDK, if you would like to install the showcase app on an Android device or emulator

  • (Optional) The latest version of XCode and command line tools for XCode available from Apple, if you would like to install the showcase app on an iOS device or emulator

For information on how to set up a local Xamarin development environment, see the Xamarin documentation.

Running your First Mobile App

Cloning the Showcase App

  • Ionic

$ git clone https://github.com/aerogear/ionic-showcase.git
$ cd ionic-showcase
$ git checkout0.8.0

Downloading the Mobile Services Configuration File

  1. Open your Mobile App in Mobile Developer Console.

  2. Copy the mobile-services.json configuration to your clipboard.

  3. Save the contents of the clipboard to a new file called mobile-services.json.

    The mobile-services.json file is the link between your provisioned services on OpenShift and the mobile app you are developing. This file provides all required configuration to initialise the various SDKs and get them hooked up/connected to the back-end services.

  4. Follow the platform-specific instructions:

  • Cordova

  • Android

  • iOS

  • Cordova

  • Xamarin

Move mobile-services.json to the following location in your application project:

src/mobile-services.json

Move mobile-services.json to the following location in your application project:

app/src/main/assets/mobile-services.json

Move mobile-services.json to the following location in your application project:

<app directory>/mobile-services.json

Ensure that mobile-services.json is a member of the project in the Xcode Project Navigator.

Move mobile-services.json to the following location in your application project:

Resources/mobile-services.json

Building and Running the Showcase App

  1. Build the Mobile App

  • Ionic

$ npm install
$ npm run ionic:build

  1. Run the Mobile App

  • Ionic

To run the showcase app, use these commands:

$ npm run ionic:android # to run on an Android device or emulator
$ npm run ionic:ios # to run on an iOS device or emulator

These commands would run the app on a device if connected or on the emulator if no device is connected.

Alternatively, you can use Cordova commands directly to specify the target:

$ ionic cordova run android --device      # run on a connected device
$ ionic cordova run android --emulator    # run on the Android emulator

Using Self-Signed Certificates in Mobile Apps

Before you can run a mobile app and connect to Mobile Services, you must configure self-signed certificates on the mobile device.

Throughout the development lifecycle of a mobile app, a common requirement is to integrate and connect with back-end services in a secure manner. This is achieved using SSL/TLS.

However, in order for the client device to connect over SSL/TLS, it needs to trust the certificates used by the back-end services, which are signed by a certificate authority. Most client devices have a list of well-known and trusted certificate authorities pre-installed and this allows the client devices to verify the certificates used by the back-end services.

A typical OpenShift development environment uses self-signed certificates that are not signed by any of the trusted certificate authorities. In such an environment, the client devices cannot establish secure connections with the back-end services that are running on a local OpenShift cluster.

The suggested workaround is to manually extract the root certificate from the cluster, install it on the device, and make sure your application trusts the new certificate.

1. Extracting the OpenShift Root Certificate Authority Cert

  1. Log into OpenShift as the admin user:

    $ oc login -u system:admin

  2. Run the following command:

    $ oc get secret router-certs --template='{{index .data "tls.crt"}}' -n default  |  \
base64 --decode | sed -e '1,/^-----END RSA PRIVATE KEY-----$/ d'  > /tmp/localcluster.crt

    The resulting file is located in the /tmp directory.

2. Installing the OpenShift Root Certificate Authority Cert on a Device

  • Android

  • iOS

To install the cert on an Android emulator:

  1. Set screen lock on the mobile device to allow for the installation of the certificate.

  2. Click on the certificate file and drag it onto the emulator. It should be copied to the Downloads folder on the device.

  3. Install the certificate on your device:

    1. To choose a file, navigate to Settings > Security & location > Advanced > Encryption & credentials > Install from SD card. From here, navigate to the Downloads folder and you should see the certificate file.

    2. Navigate to the Downloads folder and choose the certificate file. The Android system detects the certificate and lets you install it. For more information, see the sample guide for Google Nexus devices.

To install the cert on a real Android device:

  1. Enable screen lock on the mobile device to allow for the installation of the certificate.

  2. Copy the file to your device using one of the following methods:

    • Email attachment (Recommended) - Email the certificate to an address accessible from the device and download the attachment.

    • Cloud service - Use a cloud storage service such as Dropbox or Google Drive that is accessible from the device, and download from the device.

    • USB - Attach the device to a computer and drag the certificate to a devices file system.

  3. Install the certificate on your device:

    If you are use the email or cloud service method, you are prompted by the Android system automatically to install the file. Follow the instructions to complete the process.

    If you are using the USB approach, you must install the certificate manually:

    1. Go to Settings > Security & location > Advanced > Encryption & credentials > Install from SD card. You are prompted to choose a file.

    2. Navigate to the Downloads folder and choose the certificate file. The Android system detects the certificate and lets you install it. For more information, see the sample guide for Google Nexus devices.

To verify the self-signed certificate is installed correctly, use a browser on the device to open the OpenShift web console. You should not see any warnings or errors relating to the certificate.

To install the cert on an iOS simulator:

  1. Drag and drop the certificate file to the simulator, and use Safari to download the certificate to the simulator.

  2. Install the downloaded certificate:

    1. Go to Settings > General > Profile. You should see a profile with a name similar to openshift-signer@xxxxxxx.

    2. Tap on the profile. An Install button appears in the top right corner of the screen.

    3. Tap the Install button to install the cert.

  3. Trust the installed certificate in iOS. Go to Settings > General > About > Certificate Trust Settings, and enable the newly installed root certificate. See the Apple support site for more instructions.

To install the cert on a real iOS device:

  1. Enable Passcode or TouchID protection on the mobile device to ensure the certificate can be installed.

  2. Copy the file to your device using one of the following methods:

    • Email attachment (Recommended) - Email the certificate to an address accessible from the device and download the attachment.

    • Cloud service - Use a cloud storage service such as Dropbox or Google Drive that is accessible from the device, and download from the device.

  3. Add the certificate to your device:

    When you download the certificate, the device should automatically detect a profile. Follow the on screen instructions to complete the process.

  4. Trust the installed certificate in iOS. Go to Settings > General > About > Certificate Trust Settings, and enable the newly installed root certificate. See the Apple support site for more instructions.

To verify the self-signed certificate is installed correctly, use a browser on the deveice to open the OpenShift web console. You should not see any warnings or errors about the certificate.

3. Trusting the Certificate In Your App.

In the previous procedures, you ensured that the operating system trusts the cert. However, if you are using newer versions of the Android or iOS operating systems, you also need to update your mobile app to make sure it trusts the certificate.

  • Android

  • iOS

  1. Create a network_security_config.xml file with the following code.

    <network-security-config>
  <base-config>
    <trust-anchors>
      <certificates src="user"/>
      <certificates src="system"/>
    </trust-anchors>
  </base-config>
</network-security-config>

    Save this file in the following location: * res/xml directory for native apps * the root directory of the project for JavaScript apps

  2. Update the manifest file of your Android application to use this configuration.

    1. If you are developing a native application, open the AndroidManifest.xml file and add the following code to the application tag:

      <application android:networkSecurityConfig="@xml/network_security_config" ... />

    2. If you are developing a Cordova application, add the following code the config.xml file in for the android platform:

      <resource-file src="network_security_config.xml" target="app/src/main/res/xml/network_security_config.xml" />
<edit-config file="app/src/main/AndroidManifest.xml" mode="merge" target="/manifest/application">
    <application android:networkSecurityConfig="@xml/network_security_config" />
</edit-config>

      You also need to add xmlns:android="http://schemas.android.com/apk/res/android" to the widget tag in the same config.xml file.

For more information, check the Android network security configuration guide.

  1. Add the NSAllowsArbitraryLoads key to the Info.plist file of your iOS project.

  2. Set the NSAllowsArbitraryLoads key to Yes to disable the App Transport Security (ATS) feature for your application.

Only perform these steps for development or debug purposes, the resulting app will not pass the App Store review process.

For more information, see the Apple developer docs.

Running the app in an emulator

  • Android

  • iOS

  • Cordova

  • Xamarin

To run an Android app in an emulator, see the following documentation.

The AeroGear SDK supports API level 21 or later.

To run an iOS app in an emulator, see the following documentation.

Install dependencies:

  1. npm install -g cordova@8 ionic@4

  2. npm install

Cordova cross-platform applications can be run in the following emulators:

  • Android: npm run ionic:android

  • iOS: npm run ionic:ios

    A running emulator on macOS is required to run an iOS application.

Xamarin cross-platform applications are run in the following emulators:

  • Android

  • iOS

    A running emulator on macOS is required to run an iOS application.