Skip to Content

SAP Mobile Platform 3.0

Getting Started with Kapsel using SMP 3.0 SDK SP13+

Table of Contents

Overview
Setup
SAP Mobile Platform (SMP 3.0)
SAP Cloud Platform Mobile Services
Additional Required Software
Accessing the SAP OData Gateway Demo
Configuring a Kapsel App in the SAP Mobile Platform Cockpit
Configuring a Kapsel App in SAP Cloud Platform Mobile Services
Accessing the Application using the REST API
Installing Apache Cordova with Node.js
Creating an Apache Cordova Project
Running an Apache Cordova Project
Android
iOS
Windows
Kapsel Plugins
Logon
AppUpdate
Push
EncryptedStorage
Logger
Settings
AuthProxy
Barcode Scanner
Offline OData
Usage
SAP Fiori Client
Appendices:
Appendix A: OData
Appendix B: Debugging
Appendix C: Crosswalk
Appendix D: Using SAML with Kapsel
Appendix E: Non Kapsel Plugins
Appendix F: Using OAuth with Kapsel
Appendix G: SAP Web IDE, Fiori Mobile and the Hybrid Application Toolkit(HAT)
Appendix H: Tips
Appendix I: SAP Cloud Connector
Appendix J: Document Service


Overview

Note, this version of the guide covers the SAP Mobile Platform (SMP) 3.0 Kapsel Software Development Kit (SDK) version 13 and higher. The UI screens of the Logon plugin and the ability to customize the screens have changed in SP13. As well in SP11 of the SMP server, a new UI was introduced for the management cockpit. If you are using an older version of the SDK, please see Getting Started with Kapsel in SP09+.

One type of mobile app that can be written using the SMP 3.0 SDK is an HTML5 hybrid app. Apache Cordova is an open source project that provides a container with a browser that renders the UI of an application and a set of API’s that can be called from JavaScript to access native device functionality such as the device’s calendar and contacts list. The benefit of this is that the same UI code (HTML/CSS) and business logic code (JavaScript) can be deployed on multiple platforms such as iOS, Android and Windows 10 without code modifications. For additional details on how hybrid apps compare to native and other types of apps see SAP Cloud Platform Mobile Services Development Options.

Apache Cordova itself can be extended to provide additional native device functionality. For additional details on writing a Cordova plugin see Plugin Development Guide.

Kapsel is a set of plugins that enhance Apache Cordova with functionality such as a stream-lined logon to an SMP 3.0 server, offline access for OData calls, the ability to update deployed applications, encrypted storage and push notifications. For more information see Mobile Application Development Platform – Overview, the Kapsel specific enablement page at SMP 3.0 for Developers – Hybrid Apps, the blog posts by John Wargo, or Kiran Karunakaran, Sami Lechner or Michael Jess the SMP SDK product manager, the roadmap for SMP at https://www.sap.com/solution/roadmaps.platform-technology.html and the SAP Web IDE and Fiori Mobile Service for Web-IDE. For a complete list of Kapsel supported device versions see SAP Mobile SDK Supported Devices Operating Systems and Product Availability Matrix or specifically Product Availability Matrix for the SAP Mobile Platform SDK 3.0. For SMP server specific blog posts see blogs by Martin Grasshoff such as Release of SAP Mobile Platform 3.0 SP 11.

Finally, there a set of tutorials available at Mobile Interactive Tutorials that contain complete projects with guided step by step instructions demonstrating some of the key plugins of the Kapsel SDK including Logon, Offline, and Push.

Setup

Kapsel apps can be developed on Windows or Mac machines. Kapsel apps can target Android, iOS and Windows 10.
Development for an iOS device must occur on a Mac machine.
Development for Windows must occur on a Windows machine.
Android development can occur on a Windows or a Mac machine.
The Fiori Mobile service offers a service to remotely build an application.
See also Creating an Application on Windows.
Note, if using SAPUI5 or OpenUI5 on Windows 8.1 or Windows Phone 8.1, please see JavaScript Dynamic Content Shim. This shim is not needed if targeting Windows 10. Note, the examples in this blog series have not been tested with Windows 8.1.

SAP Mobile Platform (SMP 3.0)

The SAP Mobile Platform and the SAP Mobile Platform SDK can be downloaded from the SAP Software Download Center.
Alternatively a trial version of the SDK can be downloaded from SAP Mobile Platform SDK trial and the trial version of the SAP Cloud Platform can be used.
Two files need to be downloaded to install the SAP Mobile Platform 3.0. The 3.0 SP15 SDK and the 3.0 SP12 on-premise server.
Only the latest available patch level or PL needs to be applied. If PL05 is available then it can be applied directly to PL0.
Note that the PL patch for server contains two zip files. The rt-patch-3.0.11-pl04-drop2.zip file is only needed if you have installed the MBO runtime in addition to the SMP 3.0 server.
Note, that the server and SDK are on different release schedules.

Click on the Software Downloads tile.

Select Support Packages & Patches, By Alphabetical Index (A-Z) > M > SAP Mobile Platform SDK > SAP Mobile Platform SDK 3.0 > Downloads > 3.0 SP15

Select Support Packages & Patches, By Alphabetical Index (A-Z) > M > SAP Mobile Platform > SAP Mobile Platform Runtime 3.0 > Windows on x64 64bit > Download 3.0 SP13.

When running the SAP Mobile Platform Runtime 3.0 install, the MBO toolkit does not need to be installed.
The server can be started and stopped via the following shortcuts after the install completes.

The management cockpit can be accessed at https://localhost:8083/Admin.
To double check what version of the SDK installed, edit a plugin’s plugin.xml file located at C:\SAP\MobileSDK3\KapselSDK\plugins\plugin_name\plugin.xml. It should contain a version field such as the one shown below.

<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
    id="kapsel-plugin-logon"
    version="3.15.2">

The SMP server has multiple places where it indicates a version. Examine C:\SAP\MobilePlatform3\smp_product_info.xml. It should contain a version field as the one shown below.

<product name="SMPServer" version="3.0.13.0" compatibilityVersions="3.0.*">

One other place is in about dialog in the management cockpit.

SAP Cloud Platform Mobile Services

A version of the SAP Mobile Platform server is available in the cloud as a trial. It was previously abbreviated as HCPms. You can choose either the cloud offering or the on-premise SMP server. To register for the trial account, click on the link below.
SAP Cloud Platform Cockpit Trial
Once registered, click on your User ID (shown as i82XXXXtrial below).

Under Services find Development & Operations and make sure it is enabled.

Click on the Development and Operations service.
Click on Go to Service to open the service.
Note, that in May 2017, a new UI was added. The old UI which is used in this blog series can be enabled as shown below.

Additional Required Software

If your computer uses a proxy create the following system environment variables. Note, on a Windows machine, environment variables are added via Control Panel > System and Security > System > Advanced System Settings > Environment Variables.
On a Mac, edit the following file and prefix the variables with export (ie export no_proxy=localhost). Note you may need to enable the viewing of hidden files.

/Users/user/.bash_profile
no_proxy=localhost
http_proxy=http://proxy.phl.sap.corp:8080
https_proxy=http://proxy.phl.sap.corp:8080

On Windows, optionally download and install Git and add it to your path. This is required if you wish to install a plugin directly from git such as shown below.

cordova plugin add https://github.com/apache/cordova-plugin-console.git

Android

Install the latest available Java JDK and add the bin folder to the path. The following system environment variables should be set or modified.

JAVA_HOME=C:\Program Files\Java\jdk1.8.0_65
PATH=...;%JAVA_HOME%\bin;

The following command should succeed from a command prompt.

javac -version

Environment variables can be examined in a command prompt as shown below.

echo %JAVA_HOME%
echo %PATH%

Install Gradle and add it to the path.

C:\gradle\gradle-3.5\bin

Note, this is required in newer versions of the Android platform as mentioned Cordova Android 6.2.1 Released!

Download and install the Android command line tools such as installer_r24.4.1-windows.exe. Alternatively you can download a package that includes the ADT and Android Studio which is an IDE for Android development.
Run the SDK Manager (C:\Users\user_name\AppData\Local\Android\sdk\SDK Manager.exe). Note, if you use a proxy, it can be specified in the Android SDK Manager under Tools > Options > Proxy Settings.
Install the following bits for Android 6.0.0.

  • Android SDK Tools (latest)
  • Platform-tools (latest)
  • Build-tools Rev 23.0.x
  • SDK Platform 23
  • Google APIs Intel x86 Atom System Image (23)

Also, download and install Extras > Android Support Repository, Android Support Library and Google Repository. See also Support Library Setup.

Create a system environment variable named ANDROID_HOME.

ANDROID_HOME=C:\Users\user_name\AppData\Local\Android\sdk

Add the path to tools and platform-tools to your path.

PATH=...;%ANDROID_HOME%\tools;%ANDROID_HOME%\platform-tools

If one does not exist, create a KAPSEL_HOME environment variable.

KAPSEL_HOME=C:\SAP\MobileSDK3\KapselSDK

If your computer uses a proxy and you are developing for Android, create a folder (if one does not exist) named .gradle in your home directory and a file within it named gradle.properties.

C:\Users\i82XXX\.gradle\gradle.properties
or
/Users/i82xxx/.gradle/gradle.properties

The contents of the file might be as follows.

systemProp.http.proxyHost=proxy
systemProp.http.proxyPort=8080
systemProp.http.nonProxyHosts=*.sap.corp|localhost
systemProp.https.proxyHost=proxy
systemProp.https.proxyPort=8080
systemProp.https.nonProxyHosts=*.sap.corp|localhost

iOS

Download Xcode.

Windows 10

Download a version of Visual Studio 2015 such as Visual Studio Community.
Note, Visual Studio 2017 is not currently supported with SP15 or later.
The following options should be selected.
Programming Languages > Visual C++ > Common Tools for Visual C++ 2015
Windows and Web Development > Microsoft Web Developer Tools
Windows and Web Development > Universal Windows App Development Tools
Windows and Web Development > Universal Windows App Development Tools > Tools
Windows and Web Development > Universal Windows App Development Tools Windows 10 SDK (select if you need to support a different SDK than the one included with the Tools)

Windows and Web Development > Windows 8.1 and Windows Phone 8.0/8.1 Tools

Accessing the SAP OData Gateway Demo

Kapsel apps communicate with backend enterprise systems primarily by using OData. For additional information on OData see Appendix A: OData. SAP provides a publicly available OData endpoint at Create an account on the Gateway Demo system. Some of the samples in this guide will utilize this. Follow the instructions on the previously provided link to receive a user name and password necessary for accessing the OData source used throughout this guide. Note the password can be reset at the SAP Gateway – Demo Consumption Service page.

Ensure that the OData endpoint can be accessed by opening it in a browser.

https://sapes4.sapdevcenter.com/sap/opu/odata/IWFND/RMTSAMPLEFLIGHT

Enter the provided user name and password.

CarrierCollection is the collection that will be used.

CarrierCollection returns a list of airlines.

Note that the option ?sap-ds-debug=true can be used with SAP Netweaver Gateway OData sources. This causes HTML to be returned to the browser enabling the content to be displayed in an easier to read format and the links become clickable.

Notice that https is used.
Right-click on the lock icon to the left of the URL and choose Details > View Certificate.

Notice that the certificate used by sapes4.sapdevcenter.com was issued by the CA Go Daddy. In order for the SMP server to successfully connect over HTTPS to this site, the SMP server needs to trust this CA. The list of trusted CA’s can be viewed in the management cockpit under Settings > Certificates.

If this CA was not present it could be added by following the below steps which will export a certificate from Chrome and import it into the SMP server. Again these steps are not required and are included for demonstration purposes only as the GO Daddy CA is already installed in the SMP server.

  • Click on the Certificate Path tab
  • Select Go Daddy Root Certificate Authority – G2
  • View Certificate
  • In the Details tab, Copy To File…
  • Export the certificate as Base-64

Import the certificate into the SMP 3.0 server’s keystore using the import button.
Note the SMP server needs to be restarted after making this change.

The SMP server has 2 different keystores. The smp_keystore.jks contains trusted CA certificates for validation purposes and technical user certificates (with private keys) for accessing backend systems. The local_smp_keystore.jks holds only server certificates for HTTPS listeners.

Configuring a Kapsel App in the SAP Mobile Platform Cockpit

The SMP 3.0 server provides authentication, logging and the ability to rewrite the URLs of an OData endpoint. The SMP authentication providers enable the use of an existing authentication system to authenticate users accessing mobile applications. Rewriting URL’s can hide from the end user the host name of the OData endpoint. For additional details see SAP Mobile Platform Server as an OData Proxy.

The following steps will demonstrate how to configure a new hybrid or Kapsel app in the SMP 3.0 management cockpit.

Create a new application in the management cockpit. The management cockpit can be accessed at

https://localhost:8083/Admin/

The default user is smpAdmin and password is whatever was specified during the install.

Click on Applications and then on the Create Application button highlighted below.

The ID is

com.kapsel.gs

 

The OData endpoint URL is

https://sapes4.sapdevcenter.com/sap/opu/odata/IWFND/RMTSAMPLEFLIGHT

Under SSO Mechanisms, click on Add > Basic.

If the host requires a proxy to be set that the SMP server is running on, this can be set under Settings > System.

Note, changing these values requires restarting the server as indicated by pressing the ? beside the property names.

It is also recommended to set http.nonProxyHosts setting when using the http.proxyHosts setting if using the httpAuthentication provider against a server within your corporate network.

Add Security Profile

  • Under the Authentication tab, select Create New from the Security Profile Name drop down.
  • Provide a name such as SAPES4AuthProfile.
  • Add a new Authentication Provider of type HTTP/HTTPS Authentication.
  • Provide the same URL that was used for the endpoint.
    https://sapes4.sapdevcenter.com/sap/opu/odata/IWFND/RMTSAMPLEFLIGHT
  • If the Save button is disabled, switch to the ADVANCED tab, and delete the Token Expiration Interval value.

During the registration process, the SMP server will validate the provided user name and password against this URL.

Ping the endpoint to confirm that it is correctly configured.

The application is now configured in the SMP 3.0 server and ready to be used by a client application.

Configuring a Kapsel App in SAP Cloud Platform Mobile Services

One difference between the cloud and on-premise offering is how the authentication is configured.

  • Under Settings > Account Security > SCIM Type choose Mobile Service SCIM.
  • Under Applications > com.kapsel.gs > Configure > INFORMATION, set the Security Configuration to be Basic.
  • Under BACK END set the Proxy Type to be Internet.
  • Under BACK END > SCIM Path to be /sap/opu/odata/IWFND/RMTSAMPLEFLIGHT
  • Add a Basic Authentication SSO Mechanism.
  • Under SCIM CONFIGURATION check Override Global SCIM Configuration and select the app’s back-end connection from the drop down.
  • The popup message “SCIM configuration needs to be specified on ‘BACKEN END’ tab” can be ignored.

Accessing the Application using the REST API

REST stands for Representational State Transfer and is an architectural style that is stateless. It uses the HTTP protocol and makes use of the verbs GET, PUT, DELETE. The SMP REST API enables standard HTTP client applications running in any platform to register with the SMP server and make use of some of its features such as push notifications.

Some of the Kapsel plugins which are covered later make use of these API’s. The Logon plugin performs registration tasks, the Settings plugin is used to get and change an applications settings, the Logger and Usage plugin can send a log or usage data to the SMP server.

Postman is an application that can be used to invoke and examine the returned responses to REST API’s. Once installed, Postman can be opened by entering the below URL which will list the installed apps in Chrome.

chrome://apps

Try it out.

{
	"variables": [],
	"info": {
		"name": "SMP 3.0 Server REST API",
		"_postman_id": "b4ae1539-925c-78d3-cb47-01624c08f684",
		"description": "",
		"schema": "https://schema.getpostman.com/json/collection/v2.0.0/collection.json"
	},
	"item": [
		{
			"name": "1 Logon Demo Service MetaData",
			"request": {
				"url": "http://10.7.186.3:8080/odata/applications/v4/com.kapsel.gs/$metadata",
				"method": "GET",
				"header": [],
				"body": {
					"mode": "formdata",
					"formdata": []
				},
				"description": ""
			},
			"response": []
		},
		{
			"name": "2 Register with SMP 3.0 Server",
			"request": {
				"url": "http://10.7.186.3:8080/odata/applications/v4/com.kapsel.gs/Connections",
				"method": "POST",
				"header": [
					{
						"key": "Content-Type",
						"value": "application/xml",
						"description": ""
					}
				],
				"body": {
					"mode": "raw",
					"raw": "<?xml version=\"1.0\" encoding=\"utf-8\"?>    \r\n<entry xmlns=\"http://www.w3.org/2005/Atom\" xmlns:m=\"http://schemas.microsoft.com/ado/2007/08/dataservices/metadata\"    \r\nxmlns:d=\"http://schemas.microsoft.com/ado/2007/08/dataservices\">    \r\n<content type=\"application/xml\">    \r\n<m:properties>    \r\n<d:DeviceType>Windows</d:DeviceType>    \r\n</m:properties>    \r\n</content> </entry>  "
				},
				"description": "Create"
			},
			"response": []
		},
		{
			"name": "3 Proxied OData Request",
			"request": {
				"url": "http://10.7.186.3:8080/com.kapsel.gs/CarrierCollection",
				"method": "GET",
				"header": [],
				"body": {
					"mode": "formdata",
					"formdata": []
				},
				"description": ""
			},
			"response": []
		},
		{
			"name": "4 Check the DevicePhoneNumber Setting",
			"request": {
				"url": "http://10.7.186.3:8080/odata/applications/v4/com.kapsel.gs/Connections('PLACE APPCID HERE')/DevicePhoneNumber",
				"method": "GET",
				"header": [
					{
						"key": "Content-Type",
						"value": "application/xml",
						"description": ""
					}
				],
				"body": {
					"mode": "raw",
					"raw": "<?xml version=\"1.0\" encoding=\"utf-8\"?>    \r\n<entry xmlns=\"http://www.w3.org/2005/Atom\" xmlns:m=\"http://schemas.microsoft.com/ado/2007/08/dataservices/metadata\"    \r\nxmlns:d=\"http://schemas.microsoft.com/ado/2007/08/dataservices\">    \r\n<content type=\"application/xml\">    \r\n<m:properties>    \r\n<d:DeviceType>Windows</d:DeviceType>    \r\n</m:properties>    \r\n</content> </entry>  "
				},
				"description": ""
			},
			"response": []
		},
		{
			"name": "5 Update the DevicePhoneNumber Setting",
			"request": {
				"url": "http://10.7.186.3:8080/odata/applications/v4/com.kapsel.gs/Connections('PLACE APPCID HERE')",
				"method": "PUT",
				"header": [
					{
						"key": "Content-Type",
						"value": "application/json",
						"description": ""
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\"DevicePhoneNumber\": \"123 456 7899\"}"
				},
				"description": ""
			},
			"response": []
		},
		{
			"name": "6 UnRegister with SMP 3.0 Server",
			"request": {
				"url": "http://10.7.186.3:8080/odata/applications/v4/com.kapsel.gs/Connections('PLACE APPCID HERE')",
				"method": "DELETE",
				"header": [
					{
						"key": "Content-Type",
						"value": "application/xml",
						"description": ""
					}
				],
				"body": {
					"mode": "raw",
					"raw": ""
				},
				"description": ""
			},
			"response": []
		},
		{
			"name": "7 Send a Push Notification",
			"request": {
				"url": "http://10.7.186.3:8080/restnotification/application/com.kapsel.gs",
				"method": "POST",
				"header": [
					{
						"key": "Content-Type",
						"value": "application/json",
						"description": ""
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\"alert\":\"New Vacation Approval Request\", \"data\":\"For (i826565) request (7)\" }"
				},
				"description": ""
			},
			"response": []
		}
	]
}
  • Save the above content to a file named SMP_REST_API_Postman_Collection.json
  • Edit the SMP_REST_API_Postman_Collection.json file and update all the url entries to point to the URL of your SMP server. Specifically replace 10.7.186.3 with the IP address of your SMP server. Then import the modified file into Postman.
    Note, if you are using SAP Cloud Platform Mobile Services, use https and the port is 443.
  • Click on 1 Logon Demo Service MetaData.
    Click on the Authorization section and enter your credentials for the app.
    Press Send to try it out.

Press the Save button so Postman does not open the next request in a separate tab.

Click on 2 Register with SMP 3.0 Server.
Choose Basic Auth from the Authorization Type drop down.
Press Send.
Press Save.
After completing this step, copy and paste the returned ApplicationConnectionId into notepad. This ID identifies a specific user’s registration to an application. This value will can also be seen in the Management Cockpit under the name Registration ID.
Future requests from a browser or a Hybrid app will include this ID in all requests.

As well various reports can be seen under the reports section. A few are shown below.

Click on 3 Proxied ODATA Request.
Press the Save button.
Notice that the backend server information is shown in the response. IE, the following can be found in the response.

<id>https://SAPES4.SAPDEVCENTER.COM:443/sap/opu/odata/IWFND/RMTSAMPLEFLIGHT/CarrierCollection('AA')</id>

The properties are described further at Application Connection Properties.
In the management cockpit, change the Rewrite Mode to be Rewrite URL on SMP.

Press the send button again and notice that the SAPES4 no longer appears in the response. This is useful so that client applications do not see what backend they are using making it easier to change the backend without needing to make client changes.

4, 5, and 6 require that the APPCID or ApplicationConnectionId be placed in the URL where the text PLACE APPCID HERE is.
Remember to press the Save button after each request to prevent future requests from opening in a new tab.
After executing 5 to send a PUT request to update the device’s phone number, the change can be seen by re-executing 4.

7 will be used in a later section of this guide that covers the Push plugin.
In the management cockpit, click on Reporting. Notice that by choosing different Usage options such as Response Time different statistics can be shown about the users of the SMP server.

Installing Apache Cordova with Node.js

Note, execute the following commands using the Windows command prompt or the OS X terminal.

If necessary, download and install Node.js from nodejs.org.
Install the recommended version (LTS Long Term Support).
Node.js and its package manager npm can be used to install Apache Cordova. The version installed can be seen by the following node command

node -v
v6.9.3

The install should have added the following entries to your path.

C:\nodejs\
C:\Users\i82XXXX\AppData\Roaming\npm

To see what packages are already globally installed use the following command.

npm ls -g

Cordova 6.1.1 should be used if using SMP 3.0 SP13 SDK.
Cordova 6.3.1 should be used if using SMP 3.0 SP14 SDK (Windows requires cordova platform add windows@4.3.1 in SP 14).
Cordova 6.5.0 should be used if using SMP 3.0 SP15 SDK (Windows requires cordova platform add windows@5.0.0, Android requires cordova platform add android@6.2.3, and iOS requires 4.4.0)
Note, if you use a proxy server you will need to configure npm as shown below.

npm config set proxy http://proxy:8080
npm config set https-proxy http://proxy:8080

The following are for illustration purposes and demonstrate how to list the current proxy settings and remove the proxy settings.

npm config list
npm config get proxy
npm config get https-proxy
npm config delete proxy
npm config delete https-proxy
npm install -g cordova@6.5.0
npm ls -g cordova
or
cordova -v

Note, the -g indicates that Apache Cordova should be installed globally. It will be placed at the location indicated by

npm root -g

Note if you are on a Mac, use

sudo npm install -g cordova@6.5.0

A specific version of Apache Cordova can be installed by specifying a version number or if the version number is not supplied then the latest version is installed.
The available versions can be seen with the info command.

npm info cordova

Uninstalling Apache Cordova

Note, this section is for illustration purposes only. Cordova should not be uninstalled to continue with this guide.

Cordova can be uninstalled by

npm uninstall -g cordova
npm cache clean

After performing the uninstall, if the following folder exists, you may wish to delete it.

C:\Users\user\.cordova

or on a Mac

~/users/user/.cordova

Creating an Apache Cordova Project

The command-line interface or CLI is used to create Cordova projects. For additional details see Command-line Interface.

Create a folder to hold the Kapsel projects such as C:\Kapsel_Projects or ~/Documents/Kapsel_Projects
A new project can now be created using

cordova -d create C:\Kapsel_Projects\KapselGSDemo com.kapsel.gs KapselGSDemo

or on a Mac

cordova -d create ~/Documents/Kapsel_Projects/KapselGSDemo com.kapsel.gs KapselGSDemo

The first parameter following create is the directory to create the project, followed by a reverse-domain-style identifier, followed by the project name.
Note, this may take a few minutes to complete as an initial download of the template project that will be used has to be downloaded.
Note, the -d flag indicates debug output and is optional but can be useful the first time this is run in case something goes wrong.

Note, on a Mac, if the above command fails due to a permission problem, it may be necessary to provide execute rights to the folder where Cordova was installed.

cd /usr/local
sudo chmod +r+x bin

To add a platform run the following command. Note each SP of Kapsel was tested with a specific platform version. Please check above for the correct version if you aren not using SP15.

cd C:\Kapsel_Projects\KapselGSDemo
or 
cd ~/Documents/Kapsel_Projects/KapselGSDemo

cordova -d platform add android@6.2.3

or

cordova -d platform add ios@4.4.0

or

cordova platform add windows@5.0.0

At this point, the root www folder contains the HTML, JavaScript and CSS used by the project.

A duplicate set (also known as platform specific set) of the files are included in each of the below directories. These files should not be modified as they are replaced with the set from the folder shown in the previous screenshot when the commands cordova prepare or cordova run are executed.

KapselGSDemo\platforms\android\assets\www
KapselGSDemo\platforms\windows\www
KapselGSDemo\platfoms\ios\www

Plugins can be added with the following commands.

cordova plugin add cordova-plugin-battery-status
cordova plugin add cordova-plugin-device
cordova plugin add cordova-plugin-vibration
cordova plugin add cordova-plugin-dialogs

Note it is possible to specify a specific version of a plugin or to specify that the plugin comes from a GIT repository.

cordova plugin add cordova-plugin-console@0.2.12
cordova plugin add cordova-plugin-console@latest
cordova plugin add https://github.com/apache/cordova-plugin-console.git#r0.2.13
cordova plugin add https://github.com/apache/cordova-plugin-console.git

Some of the base plugins are listed here.
Additional Cordova plugins can be found at Cordova Plugins.

Type cordova help plugin and examine the add command for additional details.

After the project has been created, remove the default app by deleting the contents in the following folder.

C:\Kapsel_Projects\KapselGSDemo\www

Create a new index.html file in the www folder whose contents follow.


<!DOCTYPE html>
<html>
    <head>
        <script type="text/javascript" src="cordova.js"></script>
        <!--<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">-->
        <meta name="format-detection" content="telephone=no">
        <meta name="msapplication-tap-highlight" content="no">
        <meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width">
        <title>Cordova Hello World</title>
        <script>
            var batteryStatus;

            document.addEventListener("deviceready", onInit, false);
         
            //After this event fires, the Cordova Plugins are ready to be called
            function onInit() {
                console.log("In onInit");
                window.addEventListener("batterystatus", onBatteryStatus, false);  //Note this event listener can only be added after the deviceready event fires.
                
                if (navigator.notification) { // Override default HTML alert with native dialog.  alert is not supported on windows
                    window.alert = navigator.notification.alert;
                }
            }

            function onBatteryStatus(status) {
                console.log("MOB161 Battery Status Changed");
                batteryStatus = status;
            }

            function showBatteryInfo() {
                if (batteryStatus && batteryStatus.level) {
                    alert("Battery Level is " + batteryStatus.level + " percent charged and isPlugged = " + batteryStatus.isPlugged);
                }
                else if (device.platform == "windows") {
                    alert("Battery info is not supported on Windows");
                }
                else {
                    alert("Unable to get the battery status.  Check if the cordova-plugin-battery-status plugin is installed?");
                }
            }

            function showDeviceInfo() {
                var str = "Cordova Version: " + device.cordova;
                str = str + "\nModel: " + device.model;
                str = str + "\nPlatform: " + device.platform;
                str = str + "\nDevice Version: " + device.version;
                str = str + "\nDevice Manufacturer: " + device.manufacturer;
                alert(str);
            }

            function doVibrate() {
                navigator.vibrate([500,110,500,110,450,110,200,110,170,40,450,110,200,110,170,40,500]);  //Star Wars Imperial March
            }
        </script>
    </head>
    <body>
        <h1>Cordova Plugin's Sample</h1>
        <button id="batteryBtn" onclick="showBatteryInfo()">Get Battery Info</button> <button id="deviceBtn" onclick="showDeviceInfo()">Get Device Info</button> <button id="vibrateBtn" onclick="doVibrate()">Vibrate</button>
    </body>
</html>

Edit the config.xml file and specify the below settings which set the min Android SDK to target as well as changing the target to be a Windows 10 universal app as documented here.

<platform name="android">
      ...
      <preference name="android-minSdkVersion" value="16" />
  </platform>
  <preference name="windows-target-version" value="10.0" />

The prepare command copies the files in the project/www folder to the platform specific www folders.

cordova -d prepare

Running an Apache Cordova Project

At this point the project can be opened in a development environment such as Xcode, Android Studio or Visual Studio. Alternatively, the cordova command line can also be used to build and deploy the project.
The following are a few examples using the Cordova CLI for each platform and what the application should look like once deployed and the Battery Status button is clicked on.

Android

cordova compile android (creates an apk file that can then be installed)
emulator -list-avds or android list avd (lists the emulators that are currently available)
emulator -avd Android6 (starts an existing Android emulator named Android6)
adb install platforms/android/build/outputs/apk/CordovaApp-debug.apk (installs the app on a running device or emulator)
cordova run android (performs a cordova prepare, then builds the apk and installs the app and runs it)

If the android emulator does not start due to HAXM not being installed, download and install HAXM from the Android SDK Manager and run the installer under %ANDROID_HOME%\extras\intel\Hardware_Accelerated_Execution_Manager\intelhaxm-android.exe.
If it fails to install, try turning off the following setting in Control Panel > Programs and Features > Turn Windows Features on or off > Uncheck Hyper-V.

To open the project in Android Studio choose Import Project and navigate to C:\Kapsel_Projects\KapselGSDemo\platforms\android.
The project can be run by choosing Run > Run ‘android’
Note, if you are unable to build the project in Android Studio, try running the following commands and then opening it.

cordova platform remove android
cordova platform add android --searchpath %KAPSEL_HOME%/plugins
cordova build android

iOS

For iOS the following additional components need to be installed.

sudo npm install -g ios-sim
sudo npm install -g ios-deploy

Then the below command can also be used to prepare, build and install an iOS app.

cordova run ios --list //if needed to determine a target
cordova run ios --emulator --target iPhone-7
or
cordova run ios --device

To open the project in Xcode, double click on the file

~/Documents/Kapsel_Projects/KapselGSDemo/platforms/ios/KapselGSDemo.xcodeproj

Windows

For Windows the following commands can be run.
Note if you are deploying to a phone, the phone must first be unlocked using the Windows Phone Developer Registration tool.

Note if you are deploying to a laptop or desktop enable Developer mode by clicking on the settings for developers link in the below dialog.

cordova run windows -- --archs=x64 

cordova run windows --list
cordova run windows --emulator --target 
or 
cordova run windows --device -- --archs=arm --phone

If you double click on the following file, it will open in Visual Studio and a project for each platform can be seen.

C:\Kapsel_Projects\KapselGSDemo\platforms\windows\CordovaApp.sln

By default the bolded one or default project is initially Windows Phone 8.1. Right-click on the Universal Windows project and choose Set as Startup Project (Skip this step if you are deploying to Windows 8.1 Phone).
An architecture such as x64 or ARM can be selected. These then affect the available list of available target devices.
Note that it is required to select an architecture to work with some of the Kapsel plugins. They do not support the option AnyCPU.

Note, if you attempt to install three application on a Windows phone you may encounter the following error message.

 Error: Unable to install application. The maximum number of developer applications on this phone has been reached. Please uninstall a developer application and try again.

See also, Register as an app developer.
Note, if you receive the Error, Package could not be registered, a possible workaround is to remove the sharedUserCertificates cabability in the appxmanifest file. This capability is added by the Kapsel Logon plugin. In general, the Capability entries should appear first and the DeviceCapabilities should appear second.

Kapsel Plugins

The following sections provide step by step instructions demonstrating each Kapsel plugin and a set of appendices on topics related to Kapsel app development. Note some of the plugins mentioned below such as the Barcode Scanner, Calendar, and Print plugins are based on third party plugins. They are included in the Kapsel SDK for your convenience.

Logon
AppUpdate
Push
EncryptedStorage
Logger
Settings
AuthProxy
Barcode Scanner
Offline OData
Usage
SAP Fiori Client
Appendix A: OData
Appendix B: Debugging
Appendix C: Crosswalk
Appendix D: SAML
Appendix E: Non Kapsel Plugins
Appendix F: Using OAuth with Kapsel
Appendix G: SAP Web IDE, Fiori Mobile and the Hybrid Application Toolkit(HAT)
Appendix H: Tips
Appendix I: SAP Cloud Connector
Appendix J: Document Service

Note that comments are not easily searchable in SCN. If you have a question that is not specific to the above content it would be best to create a new discussion on SCN.
To include a reference to this document, Right Click on the title and select ‘Copy Shortcut’. Paste it into the new Discussion so people will know the relevance. If you want to bring it to the attention of the author, repeat the same process with the Author’s name.

To report this post you need to login first.

18 Comments

You must be Logged on to comment or reply to a post.

  1. Wolfgang Mayer

    Hello Daniel,
    is it possible to display a bubble containing the number of specific items on the home Screen Icon, as users are used to from several other iOS apps like e-mails, Messages, …?
    Thanks & regards
    Wolfgang Mayer 

    (0) 
    1. Daniel Van Leeuwen Post author

      On iOS the Push plugin https://blogs.sap.com/2016/10/30/getting-started-kapsel-part-4-pushsp13 I believe has a badge concept that gets updated when push notifications arrive.

      In general you might be able to find a plugin that does something similar.
      Here is one that I found.
      https://www.npmjs.com/package/de.appplant.cordova.plugin.badge

      Try searching for badge at this link.
      https://cordova.apache.org/plugins/?q=badge

      Regards,

      Dan van Leeuwen

      (0) 
  2. Sascha Liebau

    Hi Daniel,

    we have a project live and there is an annoying “bug” in our app.

    Whenever you leave our iOS Cordova app open for quite a while and then execute some request (we are not sure if its a request using the offline plugin or a request which is just routed through the SMP but used as an “online only” request, we sporadically get a http login popup saying “Login to SAML SAPSSO2 at some.host.url”. The SMP is using SAML to authenticate against the global IDP and we are using MySAPSSO2 to authenticate against Gateway and R3.

    Before refreshing or flushing we always do some kind of a soft authentication, which means refreshing the SAML cookies. We dont use SAPLogon actively. SAP AuthProxy is necessarily in but we have set this preferencce in the config.xml:

    <preference name="SAPKapselHandleHttpRequests" value="false" />

    Actually we dont know where this popup comes from and I am asking around if somebody has an idea.

    Can you imagine why this is happening?

    (0) 
    1. Daniel Van Leeuwen Post author

      I would suggest that you post this as a question separate from this blog post so others may more easily find it and it does not appear to be a question or comment of this specific blog post.

      One suggestion would be to identify the request.  Fiddler can be used to proxy all connections from a device.  There are some details on how to do this in the post below.

      https://blogs.sap.com/2015/07/21/getting-started-with-kapsel-appendix-f-tips-sp09/#monitor

      I assume you have already set the below setting?

      Modify the context in the init method and add the following configuration value which indicates that the SAML session should not be refreshed automatically when the app is restarted or unlocked.

      "refreshSAMLSessionOnResume": "skip",

      Regards,

      Dan van Leeuwen

      (0) 
  3. Gerald Iakobinyi-Pich

    Hello,

    I am trying to follow this guide to build my first Mobile App, but unfortunately I am stuck at this step”Click on 2 Register with SMP 3.0 Server”, when “Accessing the Application using the REST API”:

    For me this step returns status “403 Forbidden”:

    <html>
        <head>
            <title>Error report</title>
        </head>
        <body>
            <h1>HTTP Status 403 - </h1>
        </body>
    </html>

    Also a strange thing is that when editing the application in “Mobile Service for Development and Operations”, the flag “Override Global SCIM Configuration” does not remain checked.
    I check it, hit save, I get a success message, but when I come back, the checkbox is not checked any more.

    I am using HCPms in the cloud on an trial account.

    Could you please provide me some hint of what I am doing wrong?

    Thanks,
    Gerald

    (0) 
    1. Daniel Van Leeuwen Post author

      I tried to reproduce the behavior you are encountering but was unable to.
      One other option you could perhaps try since this is a sample app would be to use a technical user.

      To do so,

      on the Account Security page, set the SCIM type to be Default Identity Provider.

      On com.kapsel.gs on the Information page, set the security configuration to be Basic

      On the Back End page set the SCIM Path to be empty

      Under SSO Mechanism, add a Basic Authentication and include your user name and password to access the OData service

      Under SCIM Configuration, leave the Override Global SCIM Configuration unchecked.

      When you register against the HCPms server you will provide your user name and password that you use to logon to HCPms with.  It will then send the OData credentials provided in the SSO Basic Auth when required.

      Hope that gets you further,

      Dan van Leeuwen

      (0) 
      1. Gerald Iakobinyi-Pich

        Hello,

        I managed to get this working.
        It turns out I got that 403 error, because I was already registered. After I have unregistered it works.
        I am now able to execute all requests from the guide.

        I did however run into trouble again using the Kapsel Logon plugin.
        I am not able to logon using the Kapsel Logon plugin, I get this error:

        I am using following context data:

        var context = {
        “serverHost”: “hcpms-sXXXXXXXtrial.hanatrial.ondemand.com”,
        “https”: “true”,
        “serverPort”: “80”,
        “user”: “SXXXXXXXX”,
        “password”: “*******”,
        “passcode”: “password”,
        “unlockPasscode”: “password”,
        “passcode_CONFIRM”: “password”,
        “oldPasscode”: “password”,
        “custom”: {
        “hiddenFields”: [“farmId”, “resourcePath”, “securityConfig”, “serverPort”, “https”]
        }
        };

        I have tried also with https set to false, it does not work wither, I am getting the same error.

        Any idea what could be causing this?

        Thanks,
        Gerald

        (0) 
  4. Ronen Argov

    Hi,

    Thank you for this guide!
    I am using it and i have noticed that in the SMP_REST_API_Postman_Collection.json file there are only steps 1-4.
    The next steps 5-7 are missing.
    Can you please add the missing steps?

    Thanks,
    Meirav

    (0) 
  5. Shivesh Ranjan

    Hi Dan,

     

    I am facing a strange issue while using Custom Fiori Client,

    Technical Environment: KapselSP13PL06, Cordova Version: 6.1.1, SMP : True, SMP Server Version: 3.0, Passcode is Enabled and set by user.

     

    Issue: We have attachment upload functionality in Fiori Application, when we upload the attachment using Android device -> It navigates to Passcode screen. -> After entering the passcode, upload is happening & its a repetitive process whenever I upload new attachment.

     

    Regards,

    Shivesh Ranjan.

     

    (0) 
  6. Tim Sheppard

    Dan,

    We’re using SP12 SMP server.  I’m trying to determine which SDK version I should be using.  In the Overview section you stated that SP13 of the SDK uses SP11 of the server, and then later under the install instructions you mentioned that the two installs needed were SDK SP14 and server SP11.  Can you tell me which SDK version we should be using with SP12 SMP server?  And is there a definitive list posted somewhere that cross references server version to SDK version?

    Thanks for your helpful blog post,

    Tim Sheppard

     

    (0) 
    1. Daniel Van Leeuwen Post author

      Sorry for any confusion.  I was trying to make the point that the UI of the management cockpit changed in SP11 of the server.

      I would recommend the latest available version of the SMP server (3.0 SP12 PL05) and the latest available version of the SDK(3.0 SP14 PL11).

      I do not know of any version incompatibilities.

       

      Regards,

      Dan van Leeuwen

       

      (0) 
  7. Tim Sheppard

    Dan,

    Great blog thanks very much.  Can you tell me if there’s a Kapsel or Cordova plugin available that will permit me to add file attachments to my iOS app?  I’m wanting to do something similar to the way iOS Mail permits you to add attachments from storage providers (such as iCloud Drive, Google Drive, OneDrive).

    I’ve done quite a bit of searching but have found nothing so far.

    Thanks ver much

    Tim Sheppard

    (0) 

Leave a Reply