Introduction to Showcase Apps

Showcase Apps

Introduction

Showcase apps demonstrate many features of Mobile Services.

These mobile apps are ready to work with the mobile services provisioned and they present an easy starting point for the developers.

Using the Showcase Apps

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

  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 Apps

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 as. Follow the steps here.

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

    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 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 DatabasesPostgresPostgreSQL, 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 MobileData 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 MobileMobile Developer Console.

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

Creating the Data Sync Mobile App binding
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
Procedure
  1. Clone the showcase app

    • Cordova

    • Android

    • iOS

    • Xamarin

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

Procedure
  1. Clone the showcase app and checkout the release tag 1.0.0

  • Cordova

  • Android

  • iOS

  • Xamarin

$ git clone https://github.com/aerogear/ionic-showcase.git
$ cd ionic-showcase
$ git checkout 1.0.0
$ git clone https://github.com/aerogear/android-showcase-template.git
$ cd android-showcase-template
$ git checkout 1.0.0
$ git clone https://github.com/aerogear/ios-showcase-template.git
$ cd ios-showcase-template
$ git checkout 1.0.0
$ git clone https://github.com/aerogear/xamarin-showcase-template.git
$ cd xamarin-showcase-template
$ git checkout 1.0.0
  1. The following steps will help you enable Push Notifications in a showcase application.

  • Cordova

  • Android

  • iOS

  • Xamarin

  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.

  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.

  1. Follow the official guide to enable push notifications for your Xcode project.

  2. Follow the official guide to generate an APNs client TLS certificate and export the client TLS identity from your Mac.

    Make sure to protect the p12 file with a password.
    The exported p12 file with the password will be used later when binding your Mobile App to the Push Notifications.

Push Notifications Service is not supported on Xamarin.

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

This section only applies to the Ionic platform.
  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 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.
  3. Copy the contents of the mobile-services.json file and paste them into the mobile-services.json located in src.

Building and Running the Showcase App

  1. Build the Mobile App

  • Cordova

  • Android

  • iOS

  • Xamarin

$ npm install
$ npm run ionic:build
$ ./gradlew assembleDebug

Run this command to install dependencies:

  1. Install CocoaPods as described in https://cocoapods.org/ if it is not already installed.

  2. Run this command to install dependencies:

    $ pod install

Run this command to install dependencies (optional):

$ nuget restore
  1. Run the Mobile App

  • Cordova

  • Android

  • iOS

  • Xamarin

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

Following command installs and runs the debug version of the showcase app on the connected device if any. If there is no connected device, it installs and runs the application on the emulator.

$ ./gradlew installDebug

Open up .xcworkspace with Xcode and click the Build & Run button in Xcode. This should start the showcase application in an emulator.

Do not use .xcodeproj. If you open up a project file instead of a workspace, dependencies will not be correctly configured.
  1. Open up xamarin-showcase-template.sln with VisualStudio.

  2. If you didn’t run nuget restore before, right click on the solution in the left pane then click on Restore Nuget Packages.

  3. In the top bar, select the project to run: Example.Android or Example.iOS

  4. Again in the top bar, select the correct configuration:

    • Debug/Release: for compiling Example.Android

    • [Debug|Release]|iPhoneSimulator: to compile and run Example.iOS on the iPhoneSimulator

    • [Debug|Release]|iPhone: to compile and run Example.iOS on a real iPhone device

  5. At the right of the configuration, select the target device (the android or iPhone version)

  6. Click on Build → Rebuild All

  7. Click on the Run button in the top left

If no android devices are selectable, it could mean that no virtual android devices has been configured. To add one, click on Tools→Device Manager→Add Device

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

Please make sure you have created a user and set up credentials first.

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.

Data Sync

This is only available in the Cordova showcase app.
To demonstrate all the features that Data Sync offers, it’s best to run the same app on multiple devices at the same time.

From the showcase app:

  1. Press the Manage Tasks menu item.

  2. View tasks created by other people and try to edit them. See them changed on other devices.

  3. Create new tasks and see them show up on other devices.

  4. Bring the device offline by switching to Airplane Mode, create a few more tasks and edit a few existing tasks. Then switch the device back online and see them changed on other devices.

Security Services

Device Security

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.

App Security

Application Trust will allow you to connect to the Mobile Security Service and that can be used to enable or disable an application from a remote console.

The service it will not disable the showcase application it will only demonstrate the functionality.

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