Onboarding to the Mobile Development Kit Client App¶

To use your Mobile Development Kit client app, onboard to the Mobile Development Kit client from your device. You can onboard in several ways.

Onboarding via URL¶

The URL to onboard to the Mobile Development Kit client is sent to you by a system-generated e-mail from the admin. This URL contains all the connection settings required for the app to be launched. You click a URL linking a system-generated e-mail from the admin to initiate the onboarding process. The URL contains a custom URL scheme followed by key / value pairs for any connection settings. You may also copy this URL and paste into a browser on the device. For example, com.sap.mdkclient://?AppId=com.sap.sam.swe&ClientId=12345... This action launches the Mobile Development Kit client. The URL gets parsed and passes the necessary branding parameters to the client so that the Mobile Development Kit client does not have to be branded with those values.

The URL Scheme can be added in the MDKProject.json under: UrlScheme e.g. "UrlScheme": "myappclient"

To launch app now: mdkclient://?AppId=ODataOnly&ClientId=abcd-1234.. without a host parameter.

Note

As mentioned previously, you receive the full URL in an e-mail that is clicked to launch app. For testing, unlike Safari on iOS we cannot paste a URL link onto a chrome browser and hit go to launch. Chrome security feature does not allow redirects. An alternative is to use Firefox or make a simple HTML page with the URL embedded there. Then push this HTML page to the device, display it in Chrome and the link can now be clicked to launch app.

Follow the process for installation mentioned in Installing the App on a User's Device.

Onboarding via Cross-Context SSO¶

The cross-context SSO feature simplifies onboarding process for the users by transferring OAuth tokens from an established session to their mobile app. For instance, a user can open the SSO onboarding URL on their desktop. Then open the native app, navigate to the QR code scanning screen, and scan the QR code before it expires. If the QR code is accurate, the native app will be onboarded automatically. The user need not enter the credentials again.

To avail this feature, navigate to Mobile Applications > Native/MDK in mobile services cockpit and enable Cross-Context SSO option in your app's security settings. Check Configuring Cross Context SSO for more information about setting up identity transfer for application onboarding.

Onboarding via Local Overrides¶

After installing the client app, you can override some of the settings that the admin has set in the MDKClient_SDK/branding/BrandedSettings.json file included in the SDK bundle. To edit the files, your admin must have the granted you the permission to enable overrides in the ConnectionSettings and Demo settings. Only the Demo object and ConnectionSettings from the BrandedSettings.json file can be overridden. The local overrides use the file Overrides.json in a user accessible directory. For iOS, this directory is the documents folder of the application. This file has the same structure as the BrandedSettings.json file, but with fewer fields as not all Branded Settings can be overridden. At build time, it is necessary to enable overrides by setting either ConnectionSettings.EnableOverrides or Demo.EnableOverrides to true. If these fields are not set or false, the client ignores the ConnectionSettings and/or Demo overrides in Overrides.json. This setting provides the app designer to limit/grant access to override.

Note

Currently, this feature is not supported in Android due to security concerns.

Onboarding via Branded Settings¶

Together with the branded definitions, some non-metadata settings can be branded into the client. This setup is usually reserved for settings a non-generic client needs before connecting to SAP Mobile Services not part of the metadata. For example: Welcome screen text, endpoint URL, and others.

Some of the Branded Settings can be set in multiple locations, the priority order is:

(Highest priority) Overrides
Branded Settings
(Lowest priority) Default Settings

Follow the process for installation mentioned in Installing the App on a User's Device.

Onboarding Passcode Flow¶

Onboarding passcode flow is the process to create and confirm your passcode.

If the logon succeeds, the End User License Agreement (EULA) displays.
Then the create and confirm passcode screens display using passcode settings come from the "PasscodePolicySettings" setting in SAP Business Technology Platforms mobile services.
- The user provided passcode is saved in the Secure Key Store.
- If the device supports bio-metrics and if the policy setting allows it from BrandedSettings.json, you can choose to set up bio-metrics.
- If you Cancel from the passcode screen, you return to the Welcome screen.
- When done creating and confirming the passcode, you redirect to the app’s “MainPage”

Note

For Android devices, there is an extra screen during the onboarding process where you can set up fingerprint access any point. For iOS devices, the system settings are used.

iOS Onboarding via In-App QR Scan¶

In the absence of any parameter from the connection settings and ConnectionSettings.EnableOverrides set to true, the Welcome screen is displayed with a Scan button. This allows the user to scan the QR code of the application that the user wants to install and configure the connection settings of the client. Upon clicking the Scan button, the user can scan a QR code either using the scanner guides or use a QR code that is present in the gallery and is made available to the user by means of a photo picker below. Once the QR code has been scanned successfully, the connection settings are saved and the user navigates to a screen that confirms the success of the QR code scan. On clicking the Continue button in the scan confirmation screen, the user is directed to the Cloud Services login page. Rest of the onboarding process is similar to the scenario when all the connection settings are present. After the user logs out from the application, the welcome screen appears with a Start button. Upon clicking the Start button, an alert view shows up with the onboarding options namely Use current application and Scan new QR code. This gives the user another opportunity to scan a new QR code and use connection settings different from the one which is currently available. In case, the user attempts to launch the application by scanning the QR code using a third-party scanner or URL onboarding and any connection parameter is absent, then on successful validation the Scan button on the Welcome Screen gets switched to Start button. If ConnectionSettings.EnableOverrides is set to false or is missing, then neither the Scan button is not shown on the Welcome Screen nor onboarding is allowed using a third party scanner.

Support Application Switch Using In-App QR Code Scanner in iOS¶

The functionality of displaying an alert view and allowing the user to choose between Use current application or Scan new QR code upon clicking the Start button on the Welcome screen is only available when ConnectionSettings.EnableOverrides is set to true and any one of the following conditions is met:

User has onboarded and logged out of the application.
All the connection parameters are present in BrandedSettings.json.
Overrides.json with ConnectionSettings is present.
User utilizes a third party scanner to scan a QR code and the Scan button gets switched to Start button.
User clicks on an onboarding URL in which case Scan button gets switched to Start button.

If ConnectionSettings.EnableOverrides is set to false or is missing and all the connection parameters are available, then on clicking the Start button, the alert view is not displayed and normal onboarding procedure is followed.

Every string in the alert view is customizable and supports localization. The string for userChoiceString is displayed only when it is set from BrandedSettings.json using an OnboardingCustomization object. In the absence of an OnboardingCustomization object, only the default strings Please select an option, Use current application and Scan new QR code are displayed.

Android Onboarding via In-App QR Scan¶

In the absence of any parameter from the connection settings and ConnectionSettings.EnableOverrides set to true, when the user clicks on Get Started from the Welcome screen, the user navigates to the Activation screen which displays a QR Code Scan button. This allows the user to scan the QR code of the application that the user wants to install and configure the connection settings of the client. Upon clicking the QR Code Scan button, the user can scan a QR code either using the scanner guides or use a QR code that is present in the gallery and is made available to the user by means of a photo picker below. Once the QR code has been scanned successfully, the connection settings are saved and the user navigates to a screen that confirms the success of the QR code scan. On clicking the Continue button in the scan confirmation screen, the user is directed to the Cloud Services login page. Rest of the onboarding process is similar to the scenario when all the connection settings are present. If the QR code could not be scanned successfully, an alert message is shown to the user. After the user logs out from the application, the Welcome screen reappears with the Get Started button. Upon clicking the Get Started button, an alert view shows up with the onboarding options namely USE CURRENT APPLICATION and SCAN NEW QR CODE. This gives the user another opportunity to scan a new QR code and use connection settings different from the one which is currently available. In case, the user attempts to launch the application by scanning the QR code using a third-party scanner or URL onboarding and any connection parameter is absent, from the Welcome screen the user is navigated to the login page directly and not to the Activation screen. If ConnectionSettings.EnableOverrides is set to false or is missing, then neither the QR Code Scan button is shown on the Activation Screen nor onboarding is allowed using a third party scanner.

Support Application Switch Using In-App QR Code Scanner in Android¶

The functionality of displaying an alert view and allowing the user to choose between USE CURRENT APPLICATION or SCAN NEW QR CODE upon clicking the Get Started button on the Welcome screen is only available when ConnectionSettings.EnableOverrides is set to true and any one of the following conditions is met:

User has onboarded and logged out of the application.
All the connection parameters are present in BrandedSettings.json.
User utilizes a third party scanner to scan a QR code.
User clicks on an onboarding URL.

If the user clicks on USE CURRENT APPLICATION, then navigation happens to the Cloud Services login page. Otherwise, if the user chooses SCAN NEW QR CODE, then the screen where the QR code is to be scanned is displayed. If ConnectionSettings.EnableOverrides is set to false or is missing and all the connection parameters are available, then on clicking the Get Started button, the alert view is not displayed and normal onboarding procedure is followed.

Every string in the alert view is customizable and supports localization. The string for userChoiceString is displayed only when it is set from BrandedSettings.json using an OnboardingCustomization object. In the absence of an OnboardingCustomization object, only the default strings Please select an option, USE CURRENT APPLICATION and SCAN NEW QR CODE are displayed.

Onboarding via Simplified QR Code¶

Onboarding QR codes are relatively dense, as they contain complete onboarding configuration information that is significantly lengthy. Devices with lower camera resolutions often face difficulties scanning these dense QR codes. To address this issue, Mobile Development Kit allows the users to scan simplified onboarding QR codes.

A simplified QR code ideally contains a single URL that serves as the gateway to access detailed onboarding configuration information stored on the mobile services server. Thus, significantly reducing the underlying information in the QR codes.

Use any QR Code generation tool to manually convert the following JSON object into a simplified QR code:

```json

{     
 "schema": "2.0",
 "mobileServicesHost": "<my-ms-mdk-app.hana.ondemand.com>"
} 
```

Replace with your server domain name which can be found under Mobile Applications > Native/MDK > Application name > API Tab: Server of your mobile services app in the cockpit (Do not include the https:// prefix). When users scan the resulting onboarding QR code, Mobile Development Kit will retrieve the full onboarding configuration from the specified mobile services host and proceed with the user onboarding.

Note

This feature is only applicable for Android devices.

Last update: April 12, 2024