SAP Kapsel Plugins For Cordova

CONFIDENTIAL

SAP Kapsel – Apache Cordova PluginsTechnical Overview

Midhun VP

August 26th, 2015

Overview of Apache Cordova and SAP Kapsel

© 2015 SAP AG. All rights reserved. 3

Container-Based Applications on Mobile Devices - Apache Cordova

Mobile Device

When a browser-based application is executed on a mobile device, the JavaScript coding normally has no access to hardware features of the mobile device such as the accelerometer, GPS location or the camera etc.In order for a web-based application to gain access to these hardware features, it is necessary to run the application within a container that acts both as a browser and provides an API to access the hardware.Apache Cordova (formerly known as PhoneGap) provides this container.


Cordova High Level Architecture

Mobile Device

Native Application

Web ViewJavaScript, CSS, HTML, etc.

Plugin JavaScript API

Native API


Native API


Native API


Native API


Cordova’s standard PlugIns

Events pause, resume, online, offline, backbutton, menubutton, …

Notification alert, confirm, prompt, beep, vibrate

Capture (Capture media files using device's media capture applications)

Storage (DB device storage interface)

Geolocation

File

Media (audio recording an playback)

Contacts


Cordova’s User Interface


Apache Cordova Benefits

Large Community of Contributors

Developer community that needs little ramp-up

Supports most devices

Web developers do not need to understand native code for customizing container

Better performance at app startup and page loading

Config.xml approach to configure web app and turn on/off plugins

Network whitelisting approach to handle most web security threats (see html5sec.org)


Kapsel - SAP Specific Plug-Ins for Cordova

SMP3 / HCPms Server

HTTP(S)

In order for a Cordova-based web application to be able to interact with SMP3/HCPms, SAP has provided a set of plugins that are collectively known as “Kapsel”. These plugins are part of the larger Mobile SDK.In this presentation, we will be focusing on the use of the Kapsel Logon and OData plugins.

Mobile Device


Kapsel SDK

Part of the SAP Mobile Client SDK. Contains Plugins

Contains Fiori Client

Command Line Interface (CLI)


Kapsel

Kapsel is a set of SAP specific plugins for Apache Cordova

Provides enterprise capabilities to a Cordova application

Fits cleanly within existing Cordova development environments and processes

Supports Android (4.0+), iOS (6.0+) and Windows 8.1 / Windows Phone 8.1

A single web application can be provisioned into the container

Cordova

AppUpdate

AuthProxy

EncryptedStorage

Logger

Logon

Push

OData

3rd party plugin3rd party plugin

Kapsel P

luginsE2E

Barcode Scanner

Online App

App Prefs


Kapsel Plugins

1. AppUpdate

2. AuthProxy

3. EncryptedStorage

4. Logon

5. Logger

6. Push

7. Offline OData

8. E2E

9. Barcode Scanner

10. Online App

11. App Preferences

12. And More…

Apache Cordova Command Line Client


Apache CordovaBefore You Start

To get started with Cordova you need a number of things in place and configured. Node.JS– contains package manager used to install/update Cordova.

– http://nodejs.org/ GIT – used to access source repositories where Cordova plugin’s and resources reside.

– Windows – install GIT from here: http://msysgit.github.io/ – OS X – install Xcode command line tools

Ant – used to build downloaded plugins– Must install on Windows; Comes with Xcode command line tools; Install here:

http://ant.apache.org/manual/install.html

http://nodejs.org/

http://msysgit.github.io/




Apache CordovaCommand Line Interface (CLI) – Overview and Project Create Command

Cordova CLI is used to create projects, add plugins to projects, add supported device platforms to projects, and much much more. Cordova CLI documentation - http://cordova.apache.org/docs/en/4.0.0/index.html To Create a Project: cordova create <Project Folder> <Package Name> <Display Text>

– Package Name and Display Text are optional and can be edited in the project’s config.xml file.– Example: cordova create HelloWorld com.example.helloworld "HelloWorld" – www folder contains web contentso javascript, css, html

http://cordova.apache.org/docs/en/4.0.0/index.html

http://cordova.apache.org/docs/en/4.0.0/index.html


Apache CordovaCommand Line Interface (CLI) – Add Supported Device Platform Command

Kapsel supports iOS, Android and Windows 8.1 platform. Adding platforms to your projects is simple with the Cordova CLI. Add Platform Command: cordova platform add <android/ios>

– Must be in Project’s root directory– Need OS X to work with iOS platform; Windows OS to work with Windows 8.1– Device specific resources copied (and downloaded if needed) into platforms/<device> directory.– Note: Android SDK tools folder must be defined on the PATH environment variable


Apache CordovaCommand Line Interface (CLI) – Prepare Platform

Once your platform independent resources are developed and placed in the project’s www folder you can prepare the platforms so they are ready for deployment. Add Prepare Platform Command:

cordova prepare <android/ios>– Moves content found in main www folder to platform’s www folder.


Apache CordovaRun Application on iOS Simulator

For iOS, you can just open the project in Xcode by double clicking on the .xcodeproj file. Then from Xcode just run it in the Simulator.


Apache CordovaRun Application on Android Emulator

Run on Emulator: cordova emulate android

Run on Device: cordova run android


AgendaOverview of Cordova and Kapsel

Working with the Cordova Command Line Interface (CLI)

How to use the Kapsel Logon Plugin

How to use the Kapsel OData Plugin for Offline Apps

How to use the Kapsel Logger Plugin

How to use the Kapsel AppUpdate Plugin

How to use the Kapsel Push Plugin

How to use the Kapsel EncryptedStorage Plugin

Basics of using SAP UI5 with Kapsel


Kapsel’s Cornerstone plugin – most plugins rely upon the services provided by the Logon plugin

Implementation of the SMP/HCPms Mobile Application Framework (MAF) Logon Module as a Cordova plugin

Manages the process of onboarding application with the SMP/HCPms server, authenticating user and so on

Where available, will interface with the MCIM client (Client Hub)

Where available, will pull certificates from Afaria

Skinable – can provide your own look and feel.

Kapsel Logon Plugin


Logon PluginAdd Plugin to Project

Cordova CLI has a command for adding plugins to your project. Cordova plugin add <plugin> --searchPath <file location to search>

– Location of plugin can be on file system path or URL.– Command must be executed in the root directory of a Cordova project.

To add the logon plugin: cordova plugin add com.sap.mp.cordova.plugins.logon --searchPath <Location of

Kapsel Plugins> Plugins are copied into the projects plugin directory:


Logon PluginLogging in to an Application

Call function init to start the logon process.

<static> init(successCallback, errorCallback, applicationId, context, logonView)

successCallback – function called when logon successful. errorCallback – function called when logon fails. applicationId – String; applicationId as defined on the SMP/HCPms server. context – optional; object that overrides Logon plugin default values. logonView – optional; use to point custom logon view.

Typically would add logon code to index.html of your Cordova application. Other functions available with the logon plugin – see documentation for details on those.

– lock, unlock, set, get, etc.


Logon PluginLogging in to an Application - CODE

function init() { //Application ID on SMP/HCPms var appId = "com.sap.flight.kapsel"; // Optional initial connection context // Sets defaults on MAF Login Component var context = { "serverHost": "10.7.96.217", //SMP 3.0 Server hostname or IP "serverPort": "8080", //SMP 3.0 Server port "https": "false", //Use HTTPS? }; // Init the Logon component sap.Logon.init(logonSuccessCallback, errorCallback, appId, context, sap.logon.IabUi); }

...

// Device is Ready! Call the init function!document.addEventListener("deviceready", init, false);


Logon PluginLogging in to an Application – CODE; Callback Functions

function logonSuccessCallback(result) { // If result is not null, we have successful login if (result) { // Set the application Context // This has all the good stuff in it applicationContext = result; // Read the Airlines from Gateway and display readAirlines(applicationContext); }}

...

function errorCallback(e) { alert("An error occurred"); alert(JSON.stringify(e));}


Logon PluginLogging in to an Application – Using the Application Context

function readAirlines(applicationContext) { //Check if user has been on-boarded if (!applicationContext) { alert("Register or unlock before proceeding"); } // Get the endpoint, user, password and setup the X-SMP-APPCID header var uri = applicationContext.applicationEndpointURL; var user = applicationContext.registrationContext.user; var password = applicationContext.registrationContext.password; var headers = {"X-SMP-APPCID" : applicationContext.applicationConnectionId}; // Create OData model from URL var oModel = new sap.ui.model.odata.ODataModel(uri, true, user, password, headers);...

}












A SAPUI5, Cordova-Based Application Running in Online Mode

SMP3/HCPms Server OData ServerSAP Gateway or HANA

HTTP(S) HTTP(S)

Since the mobile device has network connectivity, the container-based app can perform direct OData operations against the backend server using SMP3/HCPms as a proxy server.

The client app receives a real-time response from the backend server

Mobile Device


A SAPUI5, Cordova-Based Application Running in Offline Mode 1/5


1. In order to use an app in offline mode, you must first have network connectivity to the SMP3/HCPms server.

Mobile Device

HTTP(S) HTTP(S)




Offline Store


2. The Kapsel OData plugin extracts information from the backend server and stores it in an offline store held locally on the device.

Mobile Device

HTTP(S) HTTP(S)




Offline Store


2. The Kapsel OData plugin extracts information from the backend server and stores it in an offline store held locally on the device.

3. The app can now operate without the need for any network connectivity by performing operations on the data held locally in the offline store.

Mobile Device




Offline Store

4. When network connectivity is re-established, the offline store must be synchronized with the backend server. This is a 2-step process:a) Local modifications made to the offline store must be flushed to the

backend. Think of this as “pushing out the changes I have made”.

Mobile Device

HTTP(S) HTTP(S)




Offline Store

4. When network connectivity is re-established, the offline store must be synchronized with the backend server. This is a 2-step process:a) Local modifications made to the offline store must be flushed to the

backend. Think of this as “pushing out the changes I have made”.

b) The offline store must also be refreshed with any changes made by other users of the same application.Think of this as a “pulling in the changes other users have made”.

Mobile Device

HTTP(S) HTTP(S)


OData PluginAdd Plugin to Project

Cordova CLI has a command for adding plugins to your project. cordova -d plugin add <location of plugin>

– Location of plugin can be on file system path or URL.– Command must be executed in the root directory of a Cordova project.

To add the logon plugin: cordova plugin add com.sap.mp.cordova.plugins.odata --searchPath <Location of Kapsel Plugins> Plugins are copied into the projects plugin directory:


OData PluginAccessing OData Offline – createOfflineStore(…)

Call method createOfflineStore(…) to create an OfflineStore object.

<static> createOfflineStore(properties) -> sap.OfflineStoreProperties – an object with property values for creating the Offline Store. Example:

var properties = { "name": "travel”, "host": connectionInfo.serverHost, "port": connectionInfo.serverPort, "https": connectionInfo.https, "serviceRoot" : connectionInfo.serviceUrl, "definingRequests" : { "req1" : "/Products?$expand=Supplier” }, "customHeaders" : connectionInfo.headers }

var store = sap.OData.createOfflineStore(properties);


OData PluginAccessing OData Offline – OfflineStore Method open(…)

Call the open(…) method to open the offline store. Must be online at the stage!

Creates local database on the device.

open(success_callback, error_callback)success_callback – function called if store was opened successfully.error_callback – function called if error was encountered when opening store.

Example:

store.open(store_open_success, store_open_failure);


OData PluginAccessing OData Offline – applyHttpClient()

Call applyHttpClient() applies custom OData.defaultHttpClient with custom Http Client that will access local database for requests that are mapped to the Offline Store.

<static> applyHttpClient()

Example:

sap.OData.applyHttpClient();

Call when you want to go offline!

Can remove with the removeHttpClient() call:

sap.Odata.removeHttpClient();


OData PluginAccessing OData Offline – flush(…)

Flush is called on a OfflineStore object to send all the requests that occurred when offline to the server. Call when you come back online.

flush(success_callback, error_callback)

Example:

sap.OData.stores[0].flush(flush_success, flush_failure);


OData PluginAccessing OData Offline – refresh(…)

Refresh is called on an OfflineStore object to pull in the latest changes from the backend and update the OfflineStore.

refresh(success_callback, error_callback)

Example:

sap.OData.stores[0].refresh(flush_success, flush_failure);












Kapsel Logger

• Write logs back to server

Console Log

• Standard Cordova plugin – allows you to write to the console logs of the platform.

Kapsel Logger Plugin and Cordova ConsoleLog plugin


Kapsel Logger and Cordova ConsoleLog PluginAdd Plugin to Project

Cordova CLI has a command for adding plugins to your project. It must be executed in the root directory of a Cordova project. To add the Kapsel logger plugin: cordova plugin add com.sap.mp.cordova.plugins.logger --searchPath <Location of Kapsel Plugins>

To add the Cordova ConsoleLog plugin:

cordova plugin add org.apache.cordova.console


ConsoleLog PluginLogging in to an Application - CODE

Call function init to start the logon process.

<static> log(message)

Message – String; message your want to be logged on device. Example: console.log("Logon was successful!");


Logger PluginLogging messages - CODE

Several methods to log messages at different status levels.

<static> debug(message, tag, successCallback, errorCallback)

Or warn(...) or info(...) or error(...). Message – String; message you wanted logged. tag – optional String; tag to help sort the logged messages successCallBack – optional function; called on success errorCallBack – optional function; called on error

sap.Logger.info(message, tag);


Logger PluginUploading Logs to the Server

Uploads the log to the SMP/HCPms server.

<static> upload(successCallback, errorCallback)

successCallBack – function; called on success errorCallBack – function; called on error

sap.Logger.upload(function() { console.log("Logs uploaded to server successfully");}, function(e) { console.log("Upload Failed. Status: " + e.statusCode + ", Message: " + e.statusMessage);});


Log PluginActivate Logging for Client

Logging must be activated for the client on HCPms. Admin UI > Registrations and Users:


Logger PluginSetting the log level - CODE

Optional method to change log level on the server.

<static> setLogLevel(level, successCallback, errorCallback) Level - set to sap.Logger.INFO/ERROR/DEBUG/WARN successCallBack – function; called on success errorCallBack – function; called on error

Example – set log level to INFO:

sap.Logger.setLogLevel(sap.Logger.INFO, function() {console.log("Log level set");}, function() { console.log("Failed to set log level");});












• Kapsel’s Lifecycle Management plugin

• Manages remote updating web content within the Kapsel container

• www folder contents uploaded to SMP3/HCPms.

• No special coding required.

• App checks if new update is available – pulls new content from server

Kapsel AppUpdate Plugin


AppUpdate PluginAdd Plugin to Project

Cordova CLI has a command for adding plugins to your project. It must be executed in the root directory of a Cordova project. To add the AppUpdate plugin: cordova plugin add com.sap.mp.cordova.plugins.appupdate --searchPath <Location of Kapsel Plugins>

Plugins are copied into the projects plugin directory, along with dependent plugins.


AppUpdate PluginAdd Plugin to Project – config.xml

Add application version info to projects config.xml Open the config.xml file found in the project’s www folder. Before the closing “widget” tag, add the following where 1 is the version being deployed:

<preference name="hybridapprevision" value="1" />

Notice, the other configuration values here that you can change.


• Kapsel CLI will be able to package up the contents of an application and then deploy the packaged contents to the SMP3/HCPms server.

• Application defined in SMP3/HCPms will be able to support all platform types for AppUpdate.

• Commands:• kapsel package• kapsel deploy

Kapsel CLI – For AppUpdate


Kapsel CLIpackage command

The package command will package the contents of the platform www folder’s for deployment.

kapsel package [platform(s)]

Use optional platform flag to specify the platform(s) included in the package. Package web application resources into a Zip file (HTML, CSS, JavaScript files plus other

required resources) Files will be packaged to include the platform name (in lower case) plus the platform’s www

folder and the platform’s config.xml file.


Kapsel CLIdeploy command

Will deploy the packaged contents to the SMP3/HCPms server.

kapsel deploy <APP ID> <SMP_SERVER> <User> <Password>

Will make an http(s) request to the server to deploy the archive which was created with the package command

Example:kapsel deploy com.sap.flight.kapsel localhost smpAdmin s3pAdmin


AppUpdate Plugin + Kapsel CLIMaking Changes and Push to Clients

To push a new update you just need to make changes to your application, package and deploy to SMP3/HCPms. In HCPms Admin UI you will now see that Revision to is available:

When the user opens the application they will be notified the the new version:












• Manages the process of registering for push requests plus

• Exposes events which help a developer code an application to respond to push notifications

• User must be registered with SMP3/HCPms before registering for push

• SMP3/HCPms and Device must be on network that can reach APNS/GCM

• Must define push settings in SMP3/HCPms for application

Kapsel Push Plugin


Push PluginAdd Plugin to Project

Cordova CLI has a command for adding plugins to your project. It must be executed in the root directory of a Cordova project. To add the AppUpdate plugin: cordova plugin add com.sap.mp.cordova.plugins.push --searchPath <Location of Kapsel Plugins>



Define Application Push Settings in SMP 3.0

Obtain necessary notification configuration from device platform and enter into HCPms Applications Push settings:


Push PluginRegistering API

To receive a notification user must register with APNS/GCM and register their push notification token with SMP3/HCPms.

<static> registerForNotificationTypes(types, successCallback, errorCallback, notificationlistenerfunc, senderId) types – Optional; Types of notifications the application wants to receive. The different types

of notifications are expressed in notificationType. successCallback – Optional function; called on successful registration errorCallback – Optional function; called on registration failure. notificationlistenerfunc – Optional function; called when the application is open and a

notification arrives. senderId – optional String; only used for GCM – the GCM Sender ID


Push PluginRegistering - CODE

var nTypes = sap.Push.notificationType.SOUNDS | sap.Push.notificationType.ALERT | sap.Push.notificationType.BADGE;

//Register User for Pushsap.Push.registerForNotificationTypes(nTypes, registerForPushSuccess, registerForPushFailure, proccessNotification, “Optional GCM Sender ID");

function proccessNotification(notification) { //Display Incoming Message alert("Notification received: " + notification.dispmsg);}


Push PluginSending a Push Notification

SMP provides a RESTful service to send push notifications. The Request should be formatted with the following:HTTP Method: POSTURL: http://<smp_server_hostname>:8080/Notification/<registration_id> Request Header for GCM (other header types defined – check help): X-SMP-GCM-DATA:{"dispmsg":"Hello Kapsel","appid":"com.sap.flight.kapsel","appname":"Flight Kapsel App for RKT","reasonurl":"http://www.sap.com","reasoncode":1234} Test from a REST Client:












• Adds encrypted local storage to a Cordova application (key-value pair)

• Store/Cache application data.

• Follows W3C Web Storage API with some exceptions

• Works Asynchronously (like most things on a mobile device).

Kapsel Encrypted Storage Plugin


Encrypted Storage PluginAdd Plugin to Project

Cordova CLI has a command for adding plugins to your project. It must be executed in the root directory of a Cordova project. To add the AppUpdate plugin: cordova plugin add com.sap.mp.cordova.plugins.encryptedstorage --searchPath <Location of Kapsel Plugins>



Encrypted Storage PluginConstructor

First step to using the Encrypted Storage is to create an Encrypted Storage Object.

Constructor EncryptedStorage(storageName, storagePassword) storageName – String; name of the encrypted storage. storagePassword – Optional function; called on successful registration

Example:

var storage = new sap.EncryptedStorage("FlightStore", "abcd1234");


Encrypted Storage PluginStoring Data

The methods on the Encrypted Storage Object are Asynchronous and require callback functions. To store data call the setItem() method:

setItem(key, value, successCallback, errorCallback) key – String; key of the value being stored, used for lookup value – String; value being stored successCallback – function; will be called on success errorCallback – function; will be called on failure Example:

storage.setItem(key, value, storageSuccessCallback, storageErrorCallback);

function storageSuccessCallback() { console.log("Success");} function storageErrorCallback(errorInfo) { alert("Could not read data - " + errorInfo.message);}


Encrypted Storage PluginGetting Data

The methods on the Encrypted Storage Object are Asynchronous and require callback functions. To get data call the getItem() method:

getItem(key, successCallback, errorCallback) key – String; key of the value being stored, used for lookup successCallback – function; will be called on success with value for key errorCallback – function; will be called on failure Example:

storage.getItem(airlineDataKey, function(value) {airlineData = JSON.parse(value);}, storageErrorCallback); function storageErrorCallback(errorInfo) { alert("Could not store data - " + errorInfo.message);}


Encrypted Storage PluginGetting Data

The Encrypted Storage Object offers a number of methods to work with the stored data.

Clear all data from the storage:

clear(successCallback, errorCallback)

Remove a Key value for storage:

removeItem(key, successCallback, errorCallback)

Get Number of values stored

length(successCallback, errorCallback)











• Kapsel supports any 3rd Party HTML5 libraries. Sencha, JQuery Mobile, etc.

• Easy to use SAP Mobile UI5 with Kapsel.

• UI5 contains UI elements and OData Client API.

• Based on Model View Controller (MVC) architecture.

• For best performance package SAP Mobile UI5 with your application.

SAP Mobile UI5 and Kapsel


Making OData Calls Obtaining Connection Details

The Logon Plugin successCallBack function receives all the connection details to make an Odata call.

function successCallBack(applicationContext) { ... // Get the endpoint, user, password and application Connection ID var uri = applicationContext.applicationEndpointURL;

var user = applicationContext.registrationContext.user; var password = applicationContext.registrationContext.password;

var appConnID = applicationContext.applicationConnectionId;

...}


Making OData Calls Creating OData Model

Create an ODataModel object with the connection data. Pass the application connection ID as a header value.

var headers = {"X-SMP-APPCID" : appConnID}; // Create OData model from URL var oModel = new sap.ui.model.odata.ODataModel(uri, true, user, password, headers);


Making OData Calls Binding To UI List Element

Create the List Template and List object. The ODataModel gets bound to the List object with specified collection to access.

// Create a list template var oTemplate = new sap.m.StandardListItem({title: "{carrid}", description: "{CARRNAME}"}); // Create a List and add the model var oList = new sap.m.List(); oList.setModel(oModel); // Bind the CarrierCollection items and template oList.bindItems("/CarrierCollection", oTemplate, null, null); // Place it on the page oList.placeAt("content");


Model View Controller (MVC)

View

Controller

Model


You should now be able to Have a good understanding of what Cordova is Understand how to create Cordova projects and add Kapsel

Plugins Understand how to use the Kapsel Logon Plugin Understand how to use the Kapsel AppUpdate Plugin Understand how to push Updates to Clients Understand how to use the Kapsel Logger Plugin Understand how to use the Kapsel Push Plugin Understand how to use the Kapsel EncryptedStorage Plugin Undestand the basics of using SAP UI5 with Kapsel

Summary

Date post:	14-Apr-2017
Category:	Software
Upload:	chris-whealy
View:	3,018 times
Download:	8 times

SAP Kapsel Plugins For Cordova

Software