Chapter 2. Mobile Backend

2.1. MBaaS Targets and Environments

2.1.1. Overview

An MBaaS (Mobile Backend as a Service) is a runtime space for Cloud Apps and Cloud Services. Each MBaaS provides a Node.js runtime, a NoSQL database, a caching server, and all the Cloud APIs.

To support application lifecycle management, there’s an additional layer of isolation provided for Cloud Apps and Cloud Services, called Environments. You can configure an environment for every life-cycle stage of your project, such as Development, Testing, and Production. Cloud Apps, Cloud Services and Forms are always deployed in a particular Environment, and can be easily promoted from one Environment to another.

One MBaaS can host one or more Environments. For example, you could host Development and Testing environment together on a single MBaaS, but have a separate MBaaS dedicated for a Production Environment. Even when multiple Environments are hosted on a single MBaaS they only share system resources but still remain isolated on most levels — separate Node.js runtime, database, caching server, and also a separate host name.

2.1.2. Creating an MBaaS Target

Navigate to the Admin > MBaaS Targets section.

There are three types of MBaaS targets: FeedHenry, OpenShift 2 and OpenShift 3. Each type requires its own specific configuration as described below.

Note

An MBaaS target type cannot be changed after its creation.

2.1.2.1. FeedHenry MBaaS Target

  • MBaaS ID: A unique ID for internal reference.

    This parameter cannot be changed after the MBaaS target creation and cannot contain any special characters or uppercase letters.

  • MBaaS Label: A custom label used within the Studio.
  • MBaaS URL: The host name of the MBaaS target.
  • Username: The user name to be used when logging into the instance.
  • Password: The password to be used when logging into the instance.
  • Service Key: A key used to identify the system with the FeedHenry MBaaS.

2.1.2.2. OpenShift 2 MBaaS Target

  • MBaaS ID: A unique ID for internal reference.

    This parameter cannot be changed after the MBaaS target creation and cannot contain any special characters or uppercase letters.

  • MBaaS Label: A custom label used within the Studio.
  • MBaaS URL: The host name of the public OpenShift instance (for example openshift.redhat.com).
  • Username: OpenShift 2 user name.
  • Password: OpenShift 2 password.
  • fh-mbaas Host: Host name of a running fh-mbaas service.

    Note

    If you plan to use Forms in your apps, you need to set the fh-mbaas Host field. This requires a few additional steps to deploy an fh-mbaas service on your OpenShift instance. See Enabling Forms support in OpenShift Targets.

2.1.2.3. OpenShift 3 MBaaS Target

  • MBaaS ID: A unique ID for internal reference.

    This parameter cannot be changed after the MBaaS target creation and cannot contain any special characters or uppercase letters.

  • MBaaS Label: A custom label used within the Studio.
  • OpenShift Master URL: URL where the OpenShift Master API is available.
  • Username: OpenShift 3 user name.
  • Password: OpenShift 3 password.
  • OpenShift Router DNS: OpenShift 3 Router wildcard DNS entry, for example *.local.feedhenry.io.
  • Automatic MBaaS Installation: The automatically installed MBaaS is not optimized for resiliency and stability required in production environments. For production use, follow the manual installation steps.
  • MBaaS Service Key: Value of the FHMBAAS_KEY environment variable in the fh-mbaas service.
  • MBaaS URL: Exposed route where fh-mbaas is running in OpenShift.

After you set up an MBaaS target, you also must add at least one Environment. Navigate to the Admin > Environments section to add an Environment.

2.1.3. Creating an Environment

Navigate to the Admin > Environments section.

First, create a new environment using the Create Environment button. You need to set the following parameters:

  • Environment ID: A unique ID for internal reference.

    This parameter cannot be changed after the environment creation and cannot contain any special characters or uppercase letters.

  • Environment Label: A custom label used within the Studio.
  • MBaaS Target: The MBaaS Target to be used by the Environment. An Environment can only use one MBaaS target.

Cloud Apps, Cloud Services and Forms can now be deployed to this new Environment.

2.2. Cloud Resources

2.2.1. Overview

In the Platform, when an app is staged or deployed, it will be running inside a container, also known as a Cloud Environment. Environment resource usage at both the container level and the app level can be managed and viewed here.

Requirements

The user must be a member of one or more teams with the following permissions:

  • Domain — Cloud Resources (View & Edit)
  • Domain — Projects (View)

2.2.2. Summary View

Once the page is loaded, the resource summary view is presented. You can see what cloud environments are available in your domain and current overall usage of CPU, memory and disk of an environment. Each summary view can be expanded by clicking on it.

2.2.3. Resources

You can view the detailed usage of memory, CPU and disk resources in this view. The "Dashboard" view contains an overall view of all three resources and each resource’s tab contains both the environment and per-app usage.

2.2.4. Apps

You can see all the apps that are currently running inside the environment, see their status, resource usages and manage them as well. Note you will be able to control embed apps (deployed through the build embed app wizard) here as well.

2.2.5. Cache

You can see the current cache usage of the environment, flush the cache and reset maximum cache size.

2.3. Push Notifications

2.3.1. Overview

Push notifications are a mechanism which lets server-side applications initiate communication with mobile clients - to notify the user about availability of new content on the server, or even to send a short message. This is commonly used, for example, in messaging and social network applications, or any other situation where the user might wish to be informed at all times, even when not handling the mobile device.

Red Hat Mobile Application Platform (RHMAP) has integrated support for push notifications. Through a single unified API you can deliver notifications to all client devices, even across multiple different networks simultaneously with a single function call. Push notification support in RHMAP is based on the open-source project AeroGear UnifiedPush Server (UPS).

To start using push notifications now, see the Push Notifications Client API and cloud API documentation, or try the step-by-step guide Developing An Application Using Push Notifications.

2.3.2. Supported Platforms

Support for push notifications is available for all supported mobile platforms through their corresponding push notification networks:

  • Android — Firebase Cloud Messaging (FCM) (previously Google Cloud Messaging - GCM)
  • iOS — Apple Push Notification Service (APNS)
  • Windows

    • Microsoft Push Notification Service (MPNS) for native Windows Phone 8 apps and for Cordova apps on Windows
    • Windows Push Notification Service (WNS) for native Windows 8.1 and Windows 10 Universal Apps

2.3.3. How It Works

The push notification server inside RHMAP acts as a broker that distributes notifications from your Cloud App to individual push networks, which subsequently try to deliver messages to registered mobile devices.

Push notifications

  1. Initial setup

    • Enable push notification support, separately for each Client App
    • Enable all targeted variants for push notification networks, such as FCM, APNS or MPNS and provide credentials for access to the networks, such as certificates and private keys. See Obtaining credentials for push networks for more details on setting up individual networks. For Cordova apps, create a variant for each targeted platform, just like for native Client Apps.
  2. Registration
    Upon start-up, the Client App registers with the push server by calling $fh.push and thus becomes ready to receive notifications. During registration, identification and preferences of the client are sent to the server.
  3. Push API call
    A Cloud App sends a push notification by calling $fh.push. The API lets you target all, or only specific Client Apps in your project.
  4. Distribution
    The call to $fh.push is handled by the integrated push server which distributes the notification to all corresponding push networks, depending on the variants enabled in targeted Client Apps.
  5. Delivery
    Individual push notification networks handle the actual delivery to mobile devices.
  6. Reporting
    Metadata is reported back to RHMAP, including the information that the notification was delivered and whether it was opened by the end user.
Note

The fact that push notifications pass through 3rd party networks has some implications on the design of applications using them:

  • Delivery: the delivery to the target mobile devices can’t be guaranteed by RHMAP, since most push networks do not guarantee delivery.
  • Security: it is recommended never to send any sensitive or confidential information as part of a push notification. See Security Considerations for more information.

2.3.4. Sending notifications

The simplest use case is delivering a mass notification to all devices, as demonstrated in the following example:

$fh.push(
  {alert: "Hello from {ProductShortName} to all devices!"},
  {broadcast: true},
  function (err, res) {
    if (err) {
      console.log(err.toString());
    } else {
      console.log("status : " + res.status);
    }
  }
);

The Platform is capable of several modes of delivery: all devices, a filtered set of devices, or a single device. You can also choose which Client Apps in your project receive push notifications.

2.3.4.1. Client App filtering

In the cloud-side $fh.push call, you need to explicitly choose one of two modes of notification delivery:

  • broadcast - notification delivered to all Client Apps in the project
  • selected client apps - only chosen Client Apps, identified by their App IDs, will receive the notification

See the cloud Push API documentation for examples and full documentation.

2.3.4.2. Recipient filtering

When registering with the server, Client Apps report their identification and preferences to enable filtering of notifications. You can choose to deliver push notifications to all registered devices, or only to a specific subset, filtered by the available criteria:

  • alias - user identification, such as a user name or an e-mail representing a single person (with possibly multiple devices). Intended to enable a unicast communication model.
  • categories - additional filtering criterion, enabling a publish-subscribe communication model
  • device type - automatically set by the client device; a short identifier of the mobile device hardware
  • variant ID - automatically configured by the platform; can be used for addressing only chosen push networks

See the client Push API documentation for examples and full documentation.

2.3.5. Security Considerations

2.3.5.1. Notification contents

As noted before, the payload of the push notification is delivered to third-party push notification network providers, like Google or Apple. It is highly recommended not to send any sensitive personal or confidential information belonging to an individual (for example, a social security number, financial account or transaction information), or any information where the individual may have a reasonable expectation of secure transmission, as part of any push notification.

If sensitive content needs to be delivered to the device, the recommended solution is only to send a notification informing the user about availability of new content on the server. Such content can then be securely transmitted to the device through a separate trusted channel once the user reacts to the notification.

2.3.5.2. Variant secrets

A configuration file containing the variant ID and variant secret is distributed in Client App binaries to mobile devices. These credentials authorize the Client App to register with the push server. These keys should be kept secure and should not be distributed through any other channels than through the Client App binary.

In case the variant secret key is ever compromised, it can be invalidated and replaced with a new one. You can perform the key renewal in Studio, by opening a Client App’s Push section, Variants tab and clicking on Renew Variant Secret.

Warning

Note that after renewing the variant secret key, existing installations can no longer use push notifications and the new key has to be redistributed through a new version of the Client App binary.

2.3.6. Obtaining Credentials for Push Networks

For the built-in UnifiedPush Server (UPS) to be able to access the push notification networks of individual providers - Google, Apple and Microsoft - it needs to supply credentials for authentication with the provider’s push server. The required credentials and the ways to obtain them are very different for each provider. Follow the guide for your target platform and save or make note of the required credentials, which you’ll need to supply to RHMAP when setting up push network variants for your app.

2.3.6.1. Android

For step-by-step setup instructions, follow the Obtaining FCM Credentials Guide

Required credentials:

  • Server API key
  • Project number

2.3.6.2. iOS

For step-by-step setup instructions, follow the APNs Push Notifications with AeroGear’s UnifiedPush Server Guide

Required credentials:

  • Client SSL Certificate
  • Certificate passphrase

The guide asks you to provide a Bundle ID - a unique identifier of an iOS app. If you created your iOS app in Xcode and imported it into RHMAP, you most likely already have a bundle ID set up. See About Bundle IDs in official Apple documentation for more information on bundle ID and how to set it in Xcode.

If you created your iOS app in RHMAP, your app got a default bundle ID assigned, which needs to be changed to a custom value. The bundle ID is set in the property list file of your project, located at <name-of-your-project>/<name-of-your-project>-Info.plist, under the CFBundleIdentifier key.

For Cordova apps, the bundle ID can be set in Studio. In the Config tab of your app, set the Bundle Identifier field for your build target - iOS, iPhone, or iPad.

Warning

The generated Client SSL Certificate for push notifications is bound to a particular bundle ID. Therefore a change in bundle ID would require re-generation of the certificate.

2.3.6.3. Windows

MPNS

No setup is required.

For step-by-step setup instructions, follow the WNS Push Notifications with AeroGear’s UnifiedPush Server Guide

Required credentials:

  • Package SID
  • Client secret

2.3.7. Analytics

Statistics about push notifications sent to a Client App can be found in the Studio. Navigate to a Client App’s Push section and then to the Analytics tab. The available statistics include:

  • number of push messages sent to the integrated push server for dispatching to registered devices,
  • number of notifications dispatched via push networks to registered devices,
  • number of delivered notifications opened by a user,
  • average open rate,
  • number of currently registered devices.

The Push Analytics screen also provides charts for:

  • open rate,
  • breakdown by push networks.

2.3.8. Building Cordova apps with Push Notification Support

Support for push notifications in Cordova apps is provided through the aerogear-cordova-push plugin. When a push-enabled app is built in the RHMAP Build Farm, this plugin is added automatically for the particular build if it’s configured in the www/config.json file. All RHMAP Cordova templates have this plugin configured.

When building the app locally, you need to add the plugin manually using the following command:

cordova plugin add aerogear-cordova-push

See Using Cordova Plugins for more information.

2.3.9. Community Version Of UnifiedPush Server

The open-source community version of AeroGear UnifiedPush Server can still be used in your apps, by deploying UPS to OpenShift and connecting it to the Platform through the Cloud Service AeroGear Community Push Connector which is available in the Platform for this purpose. See Developing a Push Notification Application using AeroGear UnifiedPush Server for a detailed walk-through of the process. However, note that the community version is only available for evaluation purposes and is not officially supported.