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

  4. To demonstrate Data Sync:

    You can only demonstrate Data Sync on Cordova.

    1. Provision a PostgreSQL database if there isn’t one available.

      1. Login to the OpenShift web console, create a new project or use an existing one

      2. Click on the Add to Project dropdown on the top right, and choose Browse Catalog

      3. Select Databases → Postgres → PostgreSQL, and complete the wizard to start the deployment of the database. Take notes of the values for PostgreSQL Connection Username, PostgreSQL Connection Password and PostgreSQL Database Name. You will need them later.

    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

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

      Sync Application health endpoint

      health

      Sync Application metrics endpoint

      metrics

      Sync App Port

      4000

      Sync App GraphQL Endpoint

      graphql

      Database Server Hostname

      Hostname of the PostgreSQL server

      Database Server Port

      Port number of the PostgreSQL server, usually should be 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. Protect the Data Sync app using Identity Management

Setting Up the Showcase App

Prerequisites

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

Procedure

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

  • 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

  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.

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

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.

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.