Using the Showcase Mobile App

Introducing the Showcase App

Showcase apps demonstrate many features of Mobile Services. To see these features:

  1. Set up the appropriate services as described in Setting up mobile services to demonstrate Showcase App features.

  2. Set up the showcase app as described in Setting Up the Showcase App.

  3. Register your showcase app as described in Registering a Mobile App.

  4. Bind your Mobile App to the appropriate services as described in Binding the Showcase Mobile App to Mobile Services

  5. Copy the mobile-services.json file to your IDE as described in Downloading the Mobile Services Configuration File

  6. Build and run your showcase app as described in Building and Running the Showcase App.

Setting up mobile services to demonstrate Showcase App features

Prerequisites
Procedure

  1. To demonstrate Mobile Metrics, Provision the Mobile Metrics service For more information about features, see Mobile Metrics Service

  2. To demonstrate Identity Management:

    1. Provision the Identity Management service.

    2. Set up the Identity Management service.

    3. Create a new user to authenticate using the Identity Management documentation.

    4. Set credentials for the created user. Follow the steps documentation.

    For more information about features, see Identity Management Service

  3. To demonstrate Push Notifications Provision the Push Notifications service. For more information about features, see the Push Notifications Service

Demonstrating Data Sync

  1. Provision a PostgreSQL database.

    1. Log in to OpenShift and browse to an existing project, or create a new project.

    2. Click Browse Catalog and select Databases → Postgres → PostgreSQL, and complete the wizard to start the deployment of the database.

      Record the value for PostgreSQL Connection Username, PostgreSQL Connection Password, and PostgreSQL Database Name as they are required when provisioning Data Sync.

    3. Click Browse Catalog and select Mobile → Data Sync.

  2. Provision a new Data Sync app from the catalog as described in Running Data Sync in OpenShift with the following parameters:

    Field Value

    Sync Application Name

    syncshowcase

    Sync Application Docker image

    docker.io/aerogear/voyager-server-example-task

    Sync Application Docker image version

    latest

    Sync App Port

    4000

    Sync Application metrics endpoint

    /metrics

    Sync App GraphQL Endpoint

    /graphql

    Database Server Hostname

    Hostname of the PostgreSQL server, usually postgresql

    Database Server Port

    Port number of the PostgreSQL server, usually 5432

    Database Server Username

    Username of the PostgreSQL database connection

    Database Server Password

    Password of the PostgreSQL database connection

    Database name

    PostgreSQL database name

  3. Provision the Mobile Developer Console

    1. Click Browse Catalog and select Mobile → Mobile Developer Console.

    2. Complete the wizard to start the deployment of the Mobile Developer Console.

Creating the Data Sync Mobile App binding

Prerequisites

Setting up Mobile Services to Demonstrate Showcase Apps

Procedure

  1. Log in to the Mobile Developer Console by clicking on the Mobile Developer Console link within Openshift.

  2. Click Create Mobile App, and complete the wizard to create a Mobile App.

  3. Click on the newly created Mobile App and click Mobile Services.

  4. The Data Sync provisioned service should be available under the Unbound Services heading. Click Bind to App and follow the wizard.

  5. When the binding completes, click on configuration. The configuration for the Data Sync Mobile App is displayed, for example:

    {
	"version": 1,
	"namespace": "voyager",
	"clientId": "voyager-ionic-example",
	"services": [{
		"id": "8565c444-6bed-33e9-8616-0af08791569c",
		"name": "sync-app-syncshowcase-test16",
		"type": "sync-app",
		"url": "https://sync-app-syncshowcase.testbed.com/graphql",
		"config": {
			"websocketUrl": "wss://sync-app-syncshowcasetestbed.com/graphql"
		}
	}]
}

  6. Copy the content to your clipboard.

Configuring the Showcase App to point at the provisioned Data Sync service

Prerequisites

Creating the Data Sync Mobile App binding

Procedure

  1. Clone the showcase app

    • Ionic

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

  2. Paste the Data Sync Mobile App configuration content into the mobile-services.json file located within src.

Running the showcase app with Data Sync configured

Prerequisites

Configuring the Showcase App to point at the provisioned Data Sync service

Procedure

  1. Open a terminal and browse to the showcase app root folder.

  2. Install Ionic 4:

    npm install -g ionic@4

  3. Install dependencies:

    npm install

  4. Run the showcase app with Data Sync configured:

    npm run start

  5. Once the process has finished, the showcase app is displayed in a browser at http://localhost:8100/.

Setting Up the Showcase App

Prerequisites

Setting up mobile services to demonstrate Showcase App features

Procedure

  1. Clone the showcase app and checkout the release tag 0.8.0

    • Ionic

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

  1. The following steps will help you enable Push Notifications in a showcase application.

    • Ionic

    1. You will need to create a project on Firebase.

    2. Follow steps outlined here to download google-services.json from your Firebase project.

    3. Overwrite the file app/google-services.json with the google-services.json file you downloaded from Firebase Cloud Messaging console.

Binding the Showcase Mobile App to Mobile Services

  1. Bind the Mobile App to the Mobile Metrics service if you want to demonstrate the Mobile Metrics service.

  2. Bind the Mobile App to the Identity Management service if you want to demonstrate authentication.

  3. Bind the Mobile App to the Push Notifications service if you want to demonstrate Push Notifications.

    This step also creates a variant as described in Push Notifications Service terminology.

  4. Bind the Mobile App to the Data Sync app if you want to demonstrate Data Sync.

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. Save the contents of the clipboard to a new file called mobile-services.json.

    The mobile-services.json file is the link between the mobile services running on OpenShift and the mobile app you are developing. The mobile-services.json file provides all required configuration to initialise the various SDKs and connect them to the back-end services.

  3. Copy the contents of the mobile-services.json file into the mobile-services.json file located in src.

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.

Demonstrating the ShowCase App features

Identity Management

Prerequisite

Make sure you have created a user and set up credentials for that user as describe in the Keycloak Documentation.

From the showcase app:

  • Ionic

  1. To log in, click the Login button.

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

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

Data Sync

Data Sync is only available in the Cordova showcase app.
To demonstrate all the features that Data Sync offers, use the same app from multiple devices at the same time.

From the showcase app:

  1. Select the Manage Tasks menu item.

  2. View tasks created from other devices and edit them. Check that the tasks have changed from other devices.

  3. Create new tasks and see those tasks displayed on other devices.

  4. Invoke Airplane Mode to bring your device offline.

  5. Create more tasks and edit some existing tasks.

  6. Switch the device back online and see the new and edited tasks synchronized to the other devices.

Security Services

Device Checks

Device Trust page will check the mobile device for and give a security rating for the device based on the following checks

  • Debugger Detected

  • Root Access Detected

  • Emulator Access Detected

  • No Device Lock Enabled

To use Device Trust in the showcase app:

  1. Press the Security menu item.

  2. From the drop down press Device Trust.

  3. View the results of the Device security checks.

  4. Navigate to the Grafana, and view the metrics as described in Analyzing App Usage.

Mobile Security Service

Application Trust allows you to connect to the Mobile Security Service and that allows you to enable or disable a mobile app from the Mobile Security console.

To use Application Trust in the showcase app:

  1. Press the Security menu item.

  2. From the drop down press Application Trust.

  3. Navigate to the Mobile Security Service link to set the enable/disable message as described in link:Mobile Security#monitoring[Using the App Security Console].

  4. Press the CHECK THE SECURITY SERVICE button to check the message from the service.

Push Notifications

  1. Send a push notification as described in Sending a Push Notification

  2. Launch the showcase app and view the notification.

Mobile Metrics

  1. Launch the showcase app. It automatically sends app and device metrics.

  2. Navigate to the Grafana, and view the metrics.

    If you perform device security checks, related metrics are also displayed.