Backends

14 Backends

Oracle Mobile Cloud Enterprise (OMCe) is built around the concept of mobile backends, which enable you to develop and deploy groupings of APIs that are designed to support a specific set of mobile apps or bots. You can then associate one or more apps or bots with the mobile backend to access those APIs.

What Are Backends and How Can I Use Them?

In OMCe, a backend is a secure grouping of APIs and other resources for a set of apps. Within a backend, you select the APIs that you want available for those apps. For any apps that you want to receive notifications, you can also register the appropriate credentials for the given network (e.g. APNS or FCM) in the backend.

You can have multiple backends, each serving a set of applications. In addition, you can have APIs that are used by multiple backends.

When an app accesses APIs through OMCe, it is always in the context of a backend. The app authenticates with credentials (OAuth Consumer or HTTP Basic Authentication) specific to the backend or through an identity provider (or social login provider) that is mediated by your backend.

What's the Backend Development Process?

Generally speaking, using OMCe to develop apps involves these steps:

Getting the OMCe client SDK for your target platform to simplify the use of platform features such notifications, storage, sync, and location.
Developing any custom APIs that your app or bot may need.
Creating a backend and populating it with any APIs and other resources that the app or bot will need.
Configuring apps and/or bots to connect to the backend.

The development model is flexible, allowing you to largely work in parallel on APIs, backends, apps, and bots.

Creating and Populating Backends

You create and populate backends directly in OMCe. Once you have created a backend, you can:

Assign roles that can be used to access the backend.
Associate APIs and Storage collections with the backend.
Set up profiles for the apps that will use the backend.

Creating a Backend

You create a backend to serve as a secure gateway between your app and OMCe features, such as platform and custom APIs. For your app to access these resources, it authenticates with a backend.

Click to open the side menu and select Mobile Apps > Backends.
Click New Backend.
Once you complete the dialog and the backend is created, keep the Settings page open.

You’ll need to configure your app with some of this information.

Backend Authentication and Connection Info

The following authentication and connection details are generated when you create a backend and are displayed on the backend’s Settings page:

Access Keys

You can use these to control access to the backend. They are unique for each backend.
- OAuth Consumer keys are generated in the form of a client ID and a client secret.
- HTTP Basic Authentication keys are generated for you in the form of a backend ID and an anonymous key.
If you suspect that these credentials have been compromised (such as by an application handling them insecurely), click Refresh to replace the credentials with new ones, or click Revoke to cancel the existing credentials without generating replacements.

Note:
Think twice before refreshing or revoking credentials, since these actions will block any calls that any existing apps make through the backend. To get the apps working properly again after credentials have been revoked or refreshed, you need to rebuild the apps with the new credentials and redeploy them.
Environment URLs
- The Base URL is needed for all API calls. This URL is unique for each instance that you have provisioned.
- The OAuth Token Endpoint is the URL that your app needs to make OAuth token requests.
- The OAuth Authorize Endpoint is the URL that your app can use to get an authorization code to exchange for an OAuth access token.

For details on using these and other authentication methods, see Authentication in OMCe.

To make it easier to incorporate these details in your apps, use the client SDKs for your app platforms. See Client SDKs.

Role-Based Backends

You provide an additional layer of security for a backend (and, by extension, the resources it represents) by making it role-based and then designating user roles that enable access.

Click to open the side menu and select Mobile Apps > Backends.
Open the backend that you want to make role-based.
In the left navigation for the backend, click Security.
Set the Role-based Access switch to the ON position.
In the Roles field, select any roles that you want to associate with the backend.

See Mobile Users and Roles for info on how roles work.

Note:

If your app uses Facebook login, Role-based Access needs to be turned OFF.

Associating APIs with a Backend

Once you have a backend, you can use the API Catalog to select the custom APIs you want to access through that backend. The API Catalog provides detail on each API endpoint and its documentation, as well as an opportunity to test the endpoint with mock data to see what it does.

Click to open the side menu and select Mobile Apps > Backends.
Select your backend and click Open.
In the left navbar, click APIs.
Click Select APIs.
Optionally, click an API’s name to view its endpoints.
At this stage, you can click Test Endpoint to see how the API works with mock data.

For custom APIs, you can also specify that the API can be accessed without a user login. See Testing Your Custom API for more details.
Click the + (Add) icon for each API that you want to include.

Note:

Platform APIs (for Storage, Notifications, Location, etc.) are automatically available in your backends.

Associating Storage Collections with a Backend

You can associate a backend with collections so that your apps can work with data in those collections using the Storage API.

To associate your backend with an existing collection:

Click to open the side menu and select Mobile Apps > Backends.
Select your backend and click Open.
In the left navbar of the backend, click Storage.
Click Select Collections.
Start typing the name of the collection that you want to add, select the collection from the drop-down list, and click Select.

For more on collections, including creating them, see Storage.

Notification Profiles and Client Apps

If you are using notifications in an app, you can create a notifications profile to manage the network credentials. You can then register the client app in OMCe and associate it with the notifications profile and a given backend.

Setting up a notifications profile and registering the client app accomplishes the following things:

Enables you to store the ID that is needed for the app store.
Enables the app to receive notifications via OMCe.
Simplifies lifecycle management of the app and its associated backend and related artifacts.

How Notification Profiles Work

You use notifications profiles to store credentials for notification services that you use in your apps. After you create a notification profile, you can associate it with a client that you have registered for an app and associated with a backend.

How App Clients Work

Here are the principles behind app clients:

A client represents a single version of a single app binary.

For example, if you have both iOS and Android versions of an app, you would register a client for each. Similarly, if you provide an upgraded version of the app, you would register a new client to hold its metadata.
When you register a client, you specify metadata such as the application ID that is required by the platform vendor’s app store, the app version number, and a profile that contains notifications credentials.
A client can only be associated with one version of a mobile backend.

This means that when you create a new version of a mobile backend, that mobile backend doesn’t inherit any clients that you associated with the previous version of the mobile backend. So, as you create new versions of your mobile apps that use a new version of a mobile backend, you should create corresponding clients.
A client can be published and deployed in a way similar to other artifacts. When a client is deployed, its backend and other dependencies are deployed with it.

For a rundown on publishing, deploying, and versioning app profiles, see App Profile Lifecycle in Administering Oracle Mobile Cloud, Enterprise.

Getting Network Credentials for Notifications

To enable your app to send and receive notifications via OMCe, you create an app profile and configure an associated notifications profile with the appropriate network credentials. Here's how to get the network credentials for the different platforms.

Android: Google API Key

Configuring an Android mobile app for notifications requires getting a Google API Key through Firebase Cloud Messaging (FCM).

Set up your Android mobile application in FCM according to the instructions at Set Up a Firebase Cloud Messaging Client App on Android on Google’s developer site.

This page includes detailed instructions and a link to generate the required configuration file for your project, as well as information on using the Instance ID API to create and update registration tokens.

Note:
When you generate the configuration file for your app, make sure you choose to enable the Cloud Messaging service.

In the Android app’s AndroidManifest.xml file, within the <application> node, add the following entries:

<service android:name="oracle.cloud.mobile.notifications.McsRegistrationIntentService" android:exported="false" /> 
<service android:name="oracle.cloud.mobile.notifications.GcmTokenRefreshListenerService" android:exported="false">
<intent-filter>
<action android:name="com.google.android.gms.iid.InstanceID" />
</intent-filter>
</service>

Google Play Services must be added as a dependent library in the application's build file, or these services will be flagged in error.

When generation is complete, the Project Number (aka Sender ID) and API Key are displayed. You need these credentials to register the mobile app for notifications in OMCe. They are unique to the mobile app and can’t be used to send notifications to any other app. You also need these values to get a registration token from FCM and set up the connection with OMCe.

Note:

It is still possible to use Google Cloud Messaging (GCM), but you should configure new apps with FCM. See Migrate a GCM Client App for Android to Firebase Cloud Messaging on Google Developers.

iOS: Apple Secure Certificates

Notifications make special use of Apple's network, so Apple wants extra security protections. In addition to the certificate used to set up your account, you need one of the following secure certificates:

Apple Push Notification service SSL (Sandbox) certificate for developing and testing your application with notifications while you do development. Sandbox certificates are intended for automated QA environments where devices don’t change often. In most cases, spam filters should be disabled.
Apple Push Notification service SSL (Production) certificate for releasing your application to Apple’s App Store. Apple requires this certificate before you can ship your app to the public, but you can wait until your app is finished to get it.

You need your certificate to register the mobile app for notifications in OMCe. It is unique to the mobile app and can’t be used to send notifications to any other app. Once you have configured these extra certificates, you can get a device token from Apple and set up communication with OMCe, described in Setting Up a Device Handshake for iOS.

The steps for getting a Sandbox or Production certificate are very similar to the steps you used to get the first secure certificate when you set up your app. This section assumes that you already set up your Apple developer account, got the required secure certificate, and set up an Application ID and a Provisioning Profile. For further details on using notifications in iOS, see the Local and Remote Notification Programming Guide on http://developer.apple.com.

If you didn’t enable notifications in your provisioning profile when you created your App ID, go back and enable it now.
Get your certificate(s) from the Apple Developer Center. Use the App ID you set up when you created your app.

Note:
Follow Apple’s direction to create a Certificate Signing Request (CSR) file, then export it to a .p12 file to upload it to OMCe. Do not password protect the .p12 secure certificate. (Leave the password field blank when you save the .p12 file.)

Windows: WNS Credentials

Configuring a Windows mobile app for notifications requires a unique set of credentials for Windows Push Notification Service (WNS). This section assumes you have a Microsoft Developer account.

The following credentials are required to authenticate with WNS:

Client ID (also called the Package SID)
Client Secret (also called a secret key)

To get these credentials, register your mobile app in the Windows Store Dashboard, accessible from the Windows Dev Center. For details on WNS, see WNS Overview on MSDN.

You need these credentials to register the mobile app for notifications in OMCe. They are unique to the mobile app and can’t be used to send notifications to any other app.

Syniverse: SMS Credentials

To send Short Message Service (SMS) messages using the Syniverse Messaging Service, the first step is to establish a profile on the Syniverse Developer Community, where you subscribe to the service, register your app, and get credentials.

Creating a Profile on the Syniverse Developer Community

Go to the Syniverse Developer Community (developer.syniverse.com).
Click Sign Up in the top right corner of the site and enter the requested information.
If you have an invitation code from a company in the Syniverse Developer Community enter that into "Company invite code" field. If not, ignore this step.
Read and accept the Terms of Service.
Check the Captcha box and answer the challenges to prove you aren’t a robot.
Click Create profile.
When the confirmation email arrives, click the link in the email and verify your user credentials.

Subscribing to the Syniverse Messaging Service

To use SMS in your apps using the SMS short code you got from Syniverse, you need to subscribe to the Syniverse Messaging Service.

Log in to the Syniverse Developer Community (developer.syniverse.com).
Click your user name in the top right corner and select Company. Verify that your accounts have a billing address associated with them.
Navigate to Service Offerings > Messaging Offering and click Subscriptions.
Click Subscribe and select “Initial account for [Your username]”
1. Read and accept the Terms of Service.
2. Select Confirm.
3. Verify that your account is listed in Subscriptions.
If you’re using a Syniverse-provisioned public channel to test messages, you also need to add test phone numbers to the associated whitelist. (Whitelisting is only necessary when testing SMS to U.S. or Canada phone numbers and isn’t required for production apps.)
1. Click your user name in the top right corner and select Company.
2. On the Company page, click the Whitelist tab.
3. Click Add phone number and enter your phone number in the ITU-T E.164 format (i.e., +11234567890).
4. Click Send confirmation code to send a randomly generated number to the phone number in a text message.
5. Retrieve the confirmation code from the text message and enter it in the Confirmation code field. Click Add to confirm the phone number whitelist.
6. Verify that your phone number is included in the whitelist table with "Validated" status.

Before messages can be sent through the Syniverse Messaging Service, there must be an application configured in the SDC platform. Once your app is registered, you can generate the required credentials.

Log in to the Syniverse Developer Community (developer.syniverse.com).
Click Applications.
Click New application.

In the dialog:
1. Give your application a name and description and click Save.
2. Click the gear icon next to your app name and select Edit.
3. Click SDC Self Service and make sure all the options are selected.
4. Click Account & APIs and select the "Initial account for [Your username]" from the Account dropdown.
  
  Turn on the following services: Messaging, SDC Gateway Services, Event Subscription Services, Voice & Messaging and Whitelisting Services.
5. Click Save.
Generate the required credentials:
1. From the Applications page, click the gear icon next to your app name and select Edit.
2. Click Application permissions.
3. Make sure Require user token validation is unchecked.
4. Click the first check box next to your app name to give your application full entitlements.
5. Click Auth Keys to generate the credentials.
6. Copy and store the keys to a safe place on your computer.
7. Click Save.

Creating a Notifications Profile

You create notifications profiles to hold notification credentials that your apps need.

To create a notifications profile:

Click to open the side menu and select Mobile Apps > App Profiles.
Click Profiles.
In the New Profile dialog:
- Fill in the Name. This can be whatever name that will help you identify the profile most easily.
- Select the Notification Service.
- Fill in the rest of the dialog with the information required by the notification service. For details on getting credentials from your notification provider, including any additional setup steps, see Setting Up a Mobile App for Notifications.
  
  For Apple Push Notification Services (APNS), you need to register a certificate obtained from the Apple Developer portal.
  
  For Firebase Cloud Messaging (FCM), you must register server credentials obtained from the Developers Console for an Android application. (However, providing the package name is optional, because credentials may or may not be scoped to a specific app.)
  
  For Windows Notification Service (WNS), you register your app in the Windows Store Dashboard to get the credentials required to authenticate with the Windows Notification Service.
  For Syniverse (SMS), fill in the required fields:
  - Channel ID or sender address. A channel represents a collection of sender addresses, for example, a set of SMS short codes that can be used to send text-based messages. A sender address can be any long code, short code or alphanumeric ID that applications can send SMS messages from. You can use your own sender address or purchase a sender address owned by Syniverse. When sending messages via a channel, the Syniverse Messaging API service chooses the most appropriate sender address for each message and recipient. To get a Syniverse-provisioned test channel ID for testing SMS in the U.S. or Canada, go to your Syniverse Dashboard > Service Offerings > Messaging Accounts > Public Channels (U.S. apps must use the “US MT Test Channel”). To test in the U.S. or Canada, you also need to whitelist test phone numbers as described in Setting Up a Mobile App for Notifications.
  - The authentication keys you got from Syniverse: Consumer Key, Consumer Secret and Access Token.
  - By default, consent management is handled by Syniverse, but if you want your app to handle consent management or you want to register devices through the UI, deselect Consent Management Enabled.
Click Create.

Once a notifications profile is created, you can add it to a client by opening the client, selecting its Profiles tab, and clicking Select Profile.

You can add a profile to any client whose platform is valid for the profile's notification service and whose application ID matches that of the profile. If an FCM or GCM profile does not specify a package name, the profile may be used with any Android client.

Registering an App Client

Copy the bundle ID (for iOS), package name (for Android), or application ID (for Windows) so that you have it ready when creating the client.

Once you create a client, you can’t change this value, and the value needs to match that of the profile that you associate with the client.
Click to open the side menu and select Mobile Apps > App Profiles.
Click Clients.
Click New Client.
In the New Client dialog:
- Fill in the Client Display Name and Client Name.
  
  These can be whatever names that will help you identify the client most easily. The former can have spaces and the latter can’t.
  
  In most places in the user interface, the client display name is used. The client name is used for clients in packages and the trash.
- Select the Platform (iOS, Android, Windows, or Web).
- Fill in the Version Number field.
  
  This version must match the version number of the app as registered with your platform vendor.
- Fill in the fully-qualified app ID. You get this from the platform vendor.
  
  For Apple, it is the Bundle ID assigned to the application in the Xcode project.
  
  For Google, it is the Package Name for the application as declared in its manifest file.
  
  For Microsoft, it is the Application ID you gave your app when you registered it in the Windows Dashboard.
  
  For Web, it can be any unique identifier that distinguishes it from other web applications that you register.
Click Create.
On the Settings page, select a mobile backend to associate with the client from the Mobile Backend dropdown.
Click the Profiles tab and select one or more notifications profiles that you want to associate with the client.

Note:
If the notifications profile is for the notifications service of the app’s vendor (e.g. APNS for an iOS app or FCM for an Android app), the app ID (bundle ID for iOS, package name for Android, or package SID for Microsoft) for the profile must match the app ID specified for the client. A client can only be associated with a single SMS profile.

After you have registered the app client in OMCe, you have a few options for sending notifications to your app, as shown in Sending Notifications to and from Your App.

What Can I Change in a Backend?

If you haven’t yet published your backend, you can change the following parts of the backend at any time:

Notification profiles
Custom APIs (and their implementations)
Any connector APIs that are called from custom API implementations
Storage collections
App policies

Once you have published a backend, its content is frozen. At that point, you would need to create a new version of the backend to make any changes.

Note:

Though you can’t change the list of app policies in a published backend, you can change their values.

Connecting Your App to a Backend

Once you have a backend set up and an app registered with that backend, you need to configure your app code to access the backend.

Connecting your app to a backend involves these basic steps:

Adding the client SDK libraries to your app. (This step is optional, but highly recommended.)
Adding a configuration file to your app to hold environment information that your app needs to access the backend. The SDK classes that you use to make calls to the backend use the values in this file so that you don’t have to manually include them in each of your calls.
Adding calls to OMCe APIs in your app.

The APIs available include OMCe platform APIs and any custom APIs that you or other members of your team have developed in OMCe.
Testing your app.

Description of mbe-app-process.png follows

Description of the illustration mbe-app-process.png

Analytics Apps

In order for a business analyst on your team to be able to track analytics for an app, you need to register the app in OMCe and then use the client SDK to instrument the app.

See Analytics for details on instrumenting your apps.

To see how a business analyst would access and use that data in OMCe, see Analyzing Customer Data with Oracle Mobile Cloud, Enterprise.

Registering an Analytics App

So that OMCe can collect and display analytics for an app, you need to register that app in OMCe.

In OMCe, click the application picker and then click New Application.

The dropdown arrow appears to the right of the title for the currently open application that appears in the top left of the window.
In the New Application dialog, type a name for the app, select the appropriate time zone, and click Create.

The app name can be anything that you want and should be named so that you can easily identify the app (and possibly its version and platform).
Click to open the side menu and select Settings > Application to display the environment details and credentials that your app will need for sending analytics data to OMCe.

You will copy these details into the configuration file provided by the client SDK for your platform.

Associating an Analytics App with a Backend

If you have set up a backend for your apps, you can associate your analytics app with that backend. This association is useful if you are monitoring API call analytics and want to filter them by backend.

To create the association:

Click to open the side menu and select Mobile Apps > Backends.
Select the backend you want to use and click Open.
Click the backend’s Settings tab.
In the Application ID field, enter the analytics app key that was generated when you created the analytics app.

You can find this key by opening the analytics app and selecting Settings > Application.