1. Using Oracle Mobile Cloud Service
  2. Setting up Mobile Apps
  3. Client Management

4 Client Management

To simplify handling of notifications and management of the application lifecycle in Oracle Mobile Cloud Service (MCS), you can register your mobile apps in MCS as clients and associate them with a mobile backend and a Notifications profile. When it comes time to deploy an app, you can deploy the client you have registered and have its associated mobile backend and its dependencies deployed as well.

Registering a client accomplishes the following things:

  • Enables you to store the ID that is needed for the app store.

  • Enables the app to receive notifications via MCS.

  • Simplifies lifecycle management of the app and its associated mobile backend and related artifacts.

  • Enables collection of data specific to that app through the Analytics API.

How Clients Work in MCS

Here are the principles behind client registration in MCS:

  • A client in MCS 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 create 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.

  • Once the client is registered an application key is generated. In turn, you can use this key in your apps to access the client metadata. Each of the SDKs has a configuration file where you can insert this application key.

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

  • A client can be published and deployed in a way similar to other artifacts. When a client is deployed, its mobile backend and other dependencies are deployed with it.

    For a rundown on publishing, deploying, and versioning clients, see Client Lifecycle.

Profiles

Profiles serve as a place to store credentials for notification services. After you create a profile, you can associate it with multiple clients.

Creating a Profile

You create profiles to hold notification credentials that your clients need.

To create a profile:

  1. Make sure you're in the environment where you want to create the profile.

  2. Click icon to open the side menu to open the side menu and select Applications > Client Management.

  3. Click Profiles.

  4. 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) and Google Cloud Messaging (GCM), 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 MCS UI, deselect Consent Management Enabled.

  5. Click Create.

Once a 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 as a Client in MCS

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

    Note:

    You might find it more convenient to create your profiles before registering the clients so that you have these credentials in hand when creating the client. Also, you might have multiple clients that use the same profile.

  2. Make sure you're in the environment containing the version of the client you want to register.

  3. Click icon to open the side menu to open the side menu and select Applications > Client Management.

  4. Click New Client.

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

  6. Click Create.

  7. On the Settings page, select a mobile backend to associate with the client from the Mobile Backend dropdown.

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

Legacy Client Behavior

In versions of MCS previous to 16.4.1, there were some differences in how clients were handled:

  • Client registrations and notifications profiles were not divided. Instead of referring to notifications profiles, client registrations held notifications credentials directly.

  • Client registrations could apply to multiple versions of a mobile backend.

When your environment was upgraded to 16.4.1, these differences were reconciled in the following way:

  • Any existing clients were split into clients and profiles.

  • For any client that was associated with multiple versions of a mobile backend, the client only remained associated with the version of the mobile backend in which it was created.