AppUpdate Plugin Overview

The AppUpdate plugin lets an administrator remotely update the contents in the www folder of a deployed Kapsel application.

This means that updates to the Web application content only, which does not include application bundle contents outside the www folder, do not require corresponding updates to the native application bundle on the end-users’ devices.

Note: When you update Web content for applications that are distributed through a public app store, you must adhere to the policies of the app store provider, even though you do not need to go through the formal review process. Do not include updates to content that violates the terms of the app store content review policies, or change the functionality of the application.

The AppUpdate plugin requires no developer programming, but includes a JavaScript API for customizing the way that application updates occur. The AppUpdate plugin operates in a default mode unless you handle the provided callback APIs.

Configuration Parameters

These configuration parameters are mapped between the Management Cockpit and the www folder's config.xml file. See Managing Update Versions and Revisions for information about usage.

Management Cockpit	config.xml File	Example Value
Revision	hybridapprevision	1

This shows an example of app-specific settings configuration for a sample app in Management Cockpit.
appupdate_mgmt_cockpit

The settings in Management Cockpit are mapped to: Sample <AppDirectory>/www/config.xml configuration<preference name="hybridapprevision" value="1" />

Note: The revision and development versions on SAP Mobile Platform Server are independent values. The Development Version is an optional value for the administrators’ convenience, and is not used by the AppUpdate plugin. Revisions are auto incremented upon each update of the www folder archive on the server, regardless of whether the development version changes.

Update Flow

The administrator uploads a new archive of the www folder contents to SAP Mobile Platform Server, where he or she can update one or more platform versions of the www folder in an operation. The administrator specifies the minimum version of Kapsel required for the update, and the development version (for example, the build version). The SAP Mobile Platform Server auto increments the revision number when the administrator clicks Deploy or Deploy All.
For details about these administrator tasks, as well as information on the underlying REST API that you can use to automate update uploads, see administrator Guide > Application Administration > Deploying Applications > Defining Application-Specific Settings > Uploading and Deploying Hybrid Apps.
The Kapsel application with the AppUpdate plugin checks with SAP Mobile Platform Server to see if there is a later revision of the www folder contents available. If the server has a revision that is greater than the currently downloaded revision, the updated www folder is downloaded. SAP Mobile Platform Server and the AppUpdate plugin support delta downloads between revision numbers for a development version of the www folder archive. See Managing Update Versions and Revisions.
If an update to the native Kapsel application bundle is distributed, the currently downloaded revisions of the www folder contents are retained through the update. When a newer revision is available on SAP Mobile Platform Server, the delta of the www folder contents between the on-device and server revision numbers are downloaded to the Kapsel application. For application bundle updates with very large changes to the www folder contents, you can specify a hybridapprevision parameter in the application bundle's config.xml matching that revision on SAP Mobile Platform Server, so that a delta download takes place. The www folder contents in the Kapsel application bundle are then read, as if from a downloaded revision. Future revisions to the www folder contents uploaded to the SAP Mobile Platform Server are downloaded normally by the AppUpdate plugin. See Managing Update Versions and Revisions.
Once an update is downloaded by the AppUpdate plugin, there are a series of configurable behaviors for handling the end-user experience, and for when the update is applied.
The default behavior is to display a modal alert to the user with options to accept or defer updates. If the end user accepts the update, the Web application session is restarted within the Kapsel application container, and the new version is loaded.

Example 1: User Accepts App Update

The AppUpdate function starts and triggers any required log on process.
Checking event is fired by AppUpdate.
AppUpdate finds that an update is available on the server, and the downloading event fires.
Updates finish downloading.
The sap.AppUpdate.onupdateready function is triggered.
A prompt asks the user to reload the application.
The user accepts the prompt.
The sap.AppUpdate.reloadApp function is called and the updated application loads.

Example 2: User Defers Update Action

The AppUpdate function starts and triggers any required log on process.
Checking event is fired by AppUpdate.
AppUpdate finds that an update is available on the server, and the downloading event is fired.
Updates finish downloading.
The sap.AppUpdate.onupdateready function is triggered.
A prompt asks the user to reload the application.
The user cancels the prompt.
The sap.AppUpdate.onupdateready function is triggered the next time the application is resumed or started.

Configuring the AppUpdate User Experience

You can modify the user experience of the update event by using the onUpdateReady() function in the JavaScript application code. These modifications include managing the UI that is shown to the user, text strings, look and feel, position of alert, and so on. You can also add behaviors such as storing a timestamp of the last time the end user was prompted for an update, then waiting for some fixed period of time, such as a week, before again prompting the user to update.

Note: Ensure that any code written for the onUpdateReady() function that defers, or otherwise overrides, default update life cycle includes an appropriate recovery method, and does not permanently turn off updates.

Example of Overriding Default Update Behavior

You can assign a custom function to the onUpdateReady() event to override default update behavior and force an update that does not ask the user to confirm it. It can either go immediately, or the Administrator can set a date by which it goes.

To do this, add a custom function to onUpdateReady(), for example:

sap.AppUpdate.onupdateready = myCustomAppUpdateFunction

Then, in that custom function, control the update process in whatever way you want. For example, to automatically load the update without first prompting the user for permission, you can add something similar to this:

function myCustomAppUpdateFunction = {
// No notification just reload
console.log("Applying application update…");
sap.AppUpdate.reloadApp();   
}

To use your own custom prompt to warn the user that the app is ready to update, you can do something similar to this:

function myCustomAppUpdateFunction = (e){
   console.log("Confirming application update…");
  navigator.notification.confirm('Do you want to install the latest application update?', doAppUpdateContinue, 'Please confirm', 'Yes, No');
}

function doAppUpdateContinue(buttonNum){
  if (buttonNum==1) {
    console.log("Applying application update…");
   sap.AppUpdate.reloadApp();
}
};

Managing Update Versions and Revisions

SAP Mobile Platform Server with the AppUpdate plugin supports both full updates (a complete download of the www folder archive contents on the server) and delta updates (only changed files are downloaded to the device).

These rules govern how updates are downloaded to the device:

If the hybridapprevision parameter in config.xml = 0, or is omitted, the AppUpdate plugin downloads the complete www folder archive from the server the first time the device connects. There is no delta comparison between the server revision and the initial copy on the device—the full www folder is downloaded, and becomes hybridapprevision=<current_server_revision_number> on the device.
The initial copy from the application bundle functions normally, until the time that AppUpdate downloads the first revision from the server.

In other words, since the server's auto incremented Revision value starts at 1, a hybridapprevision value of 0, or an empty value in the config.xml tells the AppUpdate plugin that it is working with the application bundle copy.

If the hybridapprevision on the device (either set in config.xml, or managed by AppUpdate plugin) is greater than 0, and there is a newer revision on the server, then the AppUpdate plugin downloads only changed, new, or deleted resources—a delta update. The delta calculations are executed by SAP Mobile Platform Server before a request from the AppUpdate plugin, and are maintained for updating from any available historical revision on the server to the current revision.

This table shows an example of the update behavior. A valid update path is any distance to the right on the matrix.

Device hybridapprevision	Server Revision
	1.2.3/1	1.2.3/2	1.2.3/3	1.3.0/4	1.5.1/5	2.0.0/6
0	Full	Full	Full	Full	Full	Full
1		Delta	Delta	Delta	Delta	Delta
2			Delta	Delta	Delta	Delta
3				Delta	Delta	Delta
4					Delta	Delta
5						Delta

Domain Whitelisting

Kapsel plugins support Apache Cordova's domain whitelisting model. Whitelisting allows you to control access to external network resources. Apache Cordova whitelisting allows you to whitelist individual network resources (URLs), for example, http://www.google.com.

For information about the whitelist rules, see http://docs.phonegap.com/en/3.3.0/guide_appdev_whitelist_index.md.html.

Best Practices

For most smaller Web applications, you should simply omit the hybridapprevision parameter from the config.xml. This ensures that the revision numbering on-device and on the server is correctly aligned. The only ‘full’ download occurs upon the Kapsel application bundle's installation and initialization—all subsequent downloads will be deltas.
For large Web applications (tens of MBs or greater), setting the hybridapprevision parameter in the config.xml can greatly reduce the download volume. You should ensure that the value on-device matches the correct value for the server. Since the values on the server are auto incremented, it may be advisable when setting this parameter to complete the upload on the server before packaging and distributing the Kapsel application bundle. This ensures that the correct value is used.