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

  • Cordova

  • Android

  • iOS

  • Xamarin

$ git clone https://github.com/aerogear/ionic-showcase.git
$ cd ionic-showcase
$ git checkout 2.0.0
$ git clone https://github.com/aerogear/android-showcase-template.git
$ cd android-showcase-template
$ git checkout 2.0.0
$ git clone https://github.com/aerogear/ios-showcase-template.git
$ cd ios-showcase-template
$ git checkout 2.0.0
$ git clone https://github.com/aerogear/xamarin-showcase-template.git
$ cd xamarin-showcase-template
$ git checkout 2.0.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 the app

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.

However, this normally doesn’t work in a development environment, such as a local OpenShift cluster as it uses self-signed certificates which are not signed by any of the trusted certificate authorties. This means by default the client devices won’t be able to establish secure connections with the back-end services that are running on a local OpenShift cluster.

To work around the problem, you must manually extract the root certificate from the cluster, install it on the device and mark it as trusted.

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

  1. Set screen lock 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) - Simply 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 which is accessible from the device, browse to the certificate and proceed to download it.

    • USB - Attach the device to the machine hosting OpenShift via USB and drag the certificate to a devices file system. Here is an example guide for Google Nexus devices. It may be different for other devices.

    • Android Debug Bridge (adb) - Use the adb push command to push the certificate to device or emulator:

      $ adb push /tmp/localcluster.crt /sdcard/Download/localcluster.crt

  3. Add the certificate to your device:

    If you are using the email or cloud service approach, once the certificate file is downloaded, you will be prompted by the Android system automatically to install the file. You can simply follow the instructions to complete the process.

    However, if you are using the USB approach, you will need to install the certificate manually: go to Settings > Security > Install from storage, tap on the copied certificate file and Android system should detect the certificate and let you add it to the device. Here is a sample guide for Google Nexus devices.

  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) - Simply 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 which is accessible from the device, browse to the certificate and proceed to download it.

  3. Add the certificate to your device:

    When you download the certificate, the device should automatically detect a profile. Simply follow the on screen instructions to install it.

    Versions iOS 10.3 and later require an additional step to trust the now installed certificate. Instructions can be found on the Apple support site

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.

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

  • Android

  • 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.

From the showcase app:

  • Cordova

  • Others

  1. To log in, click the Login button.

  2. A login page is displayed, enter your credentials.

  3. Once the login is successful, go to User Profile page and see the basic and roles information about the user.

  1. Press the Authenticate menu item depending on the platform. A login screen is displayed.

  2. Log in using the credentials you set up with setting up the service.

    Once the login is successful, you will be taken back to the showcase application where you can see the roles and basic information of the user you have just logged in with.