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 Cockpit
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 😧 Using SAML with Kapsel
Appendix E: Non Kapsel Plugins
Appendix F: Using OAuth with Kapsel
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 by John Wargo, 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 martingrasshoff such as Release of SAP Mobile Platform 3.0 SP 11.
Questions on the entire SDK can be viewed using the search Questions tagged with SAP Mobile Platform SDK.
Blogs on the entire SDK can be viewed using the search Blogs tagged with SAP Mobile Platform SDK.
Finally, there are 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 instead of the on-premise SMP server.
Two files need to be downloaded to install the SAP Mobile Platform 3.0. The 3.0 SP16 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 SP16
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="4.2.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, choose the Neo Trial.
Under Services, search for Development & Operations and enable the service.
Click on the Development & Operations.
Click on Go to Service to open the service.
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_profileno_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.gitAndroid
Install the latest available Java 8 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 -versionEnvironment 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-4.X\binNote, this is required in newer versions of the Android platform as mentioned Cordova Android 6.2.1 Released!
Download and install Android Studio.
Once downloaded attempt to create a project and run it.
This will likely result in requests to download additional components such as Android SDK Platform 26 and Build Tools 26.0.x.
If your computer uses a proxy, set the proxy under File, Settings, Appearance & Behavior, System Settings, HTTP Proxy.
If you are using an Android emulator, be sure to run install Intel HAXM under the extras folder of the Android SDK folder.
Create a system environment variable named ANDROID_HOME.
ANDROID_HOME=C:\Users\YOUR_USER_NAME\AppData\Local\Android\sdkAdd the path to emulator, tools and platform-tools to your path.
PATH=...;%ANDROID_HOME%\emulator;%ANDROID_HOME%\tools;%ANDROID_HOME%\platform-toolsIf one does not exist, create a KAPSEL_HOME environment variable.
KAPSEL_HOME=C:\SAP\MobileSDK3\KapselSDKIf 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://sapes5.sapdevcenter.com/sap/opu/odata/IWFND/RMTSAMPLEFLIGHTEnter 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 sapes5.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 on-premise and cloud cockpits have different user interfaces. Be sure to follow the correct set of instructions depending on if you are using the on-premise SAP Mobile Platform Server or the SAP Cloud Platform Mobile Services.
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://sapes5.sapdevcenter.com/sap/opu/odata/IWFND/RMTSAMPLEFLIGHTUnder 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 SAPES5AuthProfile.
- Add a new Authentication Provider of type HTTP/HTTPS Authentication.
- Provide the same URL that was used for the endpoint.
https://sapes5.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 Cockpit
The on-premise and cloud cockpits have different user interfaces. Be sure to follow the correct set of instructions depending on if you are using the on-premise SAP Mobile Platform Server or the SAP Cloud Platform Mobile Services.
SAP Cloud Platform Mobile Services provides authentication and the ability to rewrite the URLs of an OData endpoint. The 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.
The following steps will demonstrate how to configure a new hybrid or Kapsel app in the SAP Cloud Platform Mobile Services cockpit. For additional details see Defining Applications.
- Under Settings > Security ensure that Mobile Service SCIM is selected with a URL of the following format.
https://hcpms-XXXXXXtrial.hanatrial.ondemand.com/
- Create a new Hybrid application with an id of
com.kapsel.gs
- Edit the Connectivity feature to specify the OData source the application will use.
Click on the create icon to create a new destination and accept the defaults except for the following values.
The URL is
https://sapes5.sapdevcenter.com/sap/opu/odata/IWFND/RMTSAMPLEFLIGHT
The SCIM Path is
/sap/opu/odata/IWFND/RMTSAMPLEFLIGHT
Set the SSO Mechanism to Basic Authentication.
The resultant destination will appear.
- Edit the security feature.
Set the Security Configuration to be Basic, check Overwrite Global Configuration and choose com.kapse.gs from the Destination Name dropdown.
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 or SAP Cloud Platform REST API Application Development Overview
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://appsTry 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://SAPES5.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 SAPES5 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
v10.15.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 -gCordova 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 ios@4.4.0)
Cordova 7.0.1 should be used if using SMP 3.0 SP16 SDK (Windows requires cordova platform add windows@5.0.0, Android requires cordova platform add android@6.2.3, and iOS requires ios@4.5.1)
Cordova 8.0 should be used if using SMP 3.1 SDK (Windows requires cordova platform add windows@5.0.0, Android requires cordova platform add android@7.0.0, and iOS requires ios@4.5.4)
Cordova 9.0 should be used if using SMP 3.2 SDK. This information is also available in the README.md file in the SDK directory.
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:8080The 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@9.0.0
npm ls -g cordova
or
cordova -vNote, the -g indicates that Apache Cordova should be installed globally. It will be placed at the location indicated by
npm root -gNote if you are on a Mac, use
sudo npm install -g cordova@9.0.0A 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 cordovaUninstalling 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 cleanAfter performing the uninstall, if the following folder exists, you may wish to delete it.
C:\Users\user\.cordovaor on a Mac
~/users/user/.cordovaCreating 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 KapselGSDemoor on a Mac
cordova -d create ~/Documents/Kapsel_Projects/KapselGSDemo com.kapsel.gs KapselGSDemoThe 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 binTo 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 are not using SP16.
cd C:\Kapsel_Projects\KapselGSDemo
or
cd ~/Documents/Kapsel_Projects/KapselGSDemo
cordova -d platform add android@8.0.0or
cordova -d platform add ios@5.0.0or
cordova platform add windows@6.0.1At 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\wwwPlugins 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="21" />
</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 prepareRunning 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 androidiOS
For iOS the following additional components need to be installed.
sudo npm install -g ios-sim
sudo npm install -g ios-deployThen 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.xcodeprojWindows
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 😧 SAML
Appendix E: Non Kapsel Plugins
Appendix F: Using OAuth with Kapsel
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.
- SAP Managed Tags:
44 Comments
