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 Client to the appropriate services as described in Binding the Showcase Mobile Client 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

Setting Up the Showcase App

Prerequisites

Android

You need the following installed on your machine:

  • Android SDK or Android Studio from Google

  • (Recommended) The latest version of OpenJDK

iOS

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
Cordova

You need the following installed on your machine:

Xamarin

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

Procedure

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

Android
$ git clone https://github.com/aerogear/android-showcase-template.git
$ cd android-showcase-template
$ git checkout 1.0.0
iOS
$ git clone https://github.com/aerogear/ios-showcase-template.git
$ cd ios-showcase-template
$ git checkout 1.0.0
Cordova
$ git clone https://github.com/aerogear/cordova-showcase-template.git
$ cd cordova-showcase-template
$ git checkout 1.0.0
Xamarin
$ 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.

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

iOS
  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 Client to the Push Notifications.
Cordova
  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.

Xamarin

Push Notifications Service is not supported on Xamarin.

Binding the Showcase Mobile Client to Mobile Services

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

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

  3. Bind the Mobile Client 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.

Downloading the Mobile Services Configuration File

  1. Navigate to your project in OpenShift.

  2. On the Overview screen, expand your Mobile Client to view the CLIENT INFO.

  3. Copy the configuration to your clipboard.

  4. 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.
  5. Follow the next specific additional instructions depending on your platform:

Android

Locate this file at the following location in your application project:

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

iOS

Locate this file at the following location in your application project:

<app directory>/mobile-services.json

Cordova

Locate this file in your application project and import it using require.

const aerogearConfig = require("./mobile-services.json");

Alternatively you can create a JavaScript object and use directly:

const aerogearConfig = /* Paste here the contents of the clipboard */;
Xamarin

Locate this file at the following location in your application project:

Resources/mobile-services.json

Building and Running the Showcase App

  1. Build the Mobile App

Android
$ ./gradlew assembleDebug
iOS

Run this command to install dependencies:

$ pod install
Cordova
$ npm install
$ npm run ionic:build
Xamarin

Run this command to install dependencies (optional):

$ nuget restore
  1. Run the Mobile App

Android

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
iOS

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

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

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

iOS
  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

Demonstrating the ShowCase App Features

Identity Management

From the showcase app:

  1. Press the Authenticate menu item. 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.

Device Security

From the showcase app:

  1. Press the Device Security menu item.

  2. View the results of the Device security checks.

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

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.