Chapter 2. Mobile Backend

2.1. MBaaS Targets and Environments

2.1.1. MBaaS (Mobile Backend as a Service)

MBaaS is a runtime space for Cloud Apps and Cloud Services. Each MBaaS provides a Node.js runtime, a MongoDB database, a caching server, and all Cloud APIs.

2.1.2. Environments

Environments add an additional layer of isolation for Cloud Apps and Cloud Services to support application lifecycle management. An Environment is hosted on MBaaS.

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.

A single MBaaS can host one or more Environments. For example, you can host Development and Testing environments together on a single MBaaS, but have a separate MBaaS dedicated for a Production Environment. Multiple Environments hosted on a single MBaaS remain isolated on most levels. They share system resources but have separate Node.js runtime, database, caching server, and a separate host name.

2.1.3. Creating OpenShift 3 MBaaS Target in RHMAP Studio

  1. Click Admin > MBaaS Targets.
  2. Set the parameters according to the instructions located under each field.
  3. Click Create MBaaS Target.
Important

After you set up an MBaaS target, add at least one Environment. See Managing Environments

2.1.4. Managing Environments

2.1.4.1. Managing Environments using RHMAP Studio

Prerequisites
  • Own correct user permissions to modify environments
2.1.4.1.1. Creating an Environment using RHMAP Studio
  1. Click Admin>Environments>Create Environment.
  2. Set the parameters according to the instructions located under each field.
  3. Click Save Environment.

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

2.1.4.1.2. Modifying and Deleting Environments using RHMAP Studio
Important

Access to modification and deleting a particular Environment can be restricted. If you are unable to delete or modify an Environment, check your user permissions.

  1. Click Admin>Environments.
  2. Choose an Environment you want to modify or delete from the table by clicking on it.
  3. Make desired changes to Environment Label and click Save Environment.
  4. To delete an Environment, click Delete this Environment.
2.1.4.1.3. Configuring Environments using RHMAP Studio
  1. Click Admin>Environments>Configure Environments.
  2. Reorder the Environments by dragging the Environment labels.

This is reflected in the order of Environments in Lifecycle Dashboard.

2.1.4.2. Managing Environments with fh-fhc CLI

This section contains a list of commands used to manage Environments. Follow the instructions presented after entering the command without arguments.

Prerequisites
2.1.4.2.1. Listing Available Environments using fh-fhc CLI

This command prints a table of available Environments with basic Environment properties. No arguments required.

$ fhc admin environments list
2.1.4.2.2. Displaying Environment Properties using fh-fhc CLI

Use this command to show Environment properties in JSON format:

$ fhc admin environments read
2.1.4.2.3. Creating Environment using fh-fhc CLI
$ fhc admin environments create
2.1.4.2.4. Deleting Environment using fh-fhc CLI
$ fhc admin environments delete
2.1.4.2.5. Updating Environments using fh-fhc CLI

Use this command to update an Environment label, MBaaS Target or OpenShift token:

$fhc admin environments update
Additional Resources

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

The summary view displays the Cloud’s resources at a summary level, and each summary view is expanded by clicking on it. Available cloud environments and also CPU, memory, disk and inode usage is displayed.

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 notification is a mechanism that allows server-side applications to initiate communication with mobile clients, to notify the user about availability of new content on the server, or 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 Hosted (RHMAP) has integrated support for push notification networks. Through a single unified API, you can deliver notifications to all client devices, even across multiple different networks simultaneously with a single function call. Do note that individual push notification networks handle the actual delivery of a notification to mobile devices. Push notification support in RHMAP is based on the open-source project AeroGear UnifiedPush Server (UPS).

In the Studio, there are 4 sections that provide information about push notifications:

  1. Analytics - See Analytics for more information
  2. Variants - Create and manage a group of devices that are targeted by notifications
  3. Sender API - Sender APIs are supported and enable the backend server to send push notifications
  4. Activity log - Displays the details for all push messages

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

2.3.3. How It Works

RHMAP push notification acts as a broker that distributes notifications from your Cloud App to individual push networks, for example, FCM or APNS. Individual push notification networks handle the actual delivery to 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 or APNS, 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 - one or more users represented by user identification, such as a user names or an e-mail addresses (possibly each with multiple devices).
  • 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 and Apple - 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 Identifier can be set manually. Open the app’s config.xml file in an editor and set the value in the <widget id=""> field.

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.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 delivered notifications opened by a user
  • average open rate
  • number of currently registered devices
  • number of notifications dispatched via push networks to registered devices

    • to activate the notifications dispatched metric, turn it on in the relevant Client SDK: iOS, Android, Cordova

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 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 (UPS) 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. However, note that the community version is only available for evaluation purposes and is not officially supported.