Developer

AppUpdate Plugin

(Android and iOS) Remotely update contents in the www folder and the config.xml of a deployed Hybrid SDK (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.

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 administration cockpit and the Cordova CLI project folder's config.xml file. See Managing Update Versions and Revisions for information about usage.

Cockpit config.xml File Example Value
Revision hybridapprevision 1

This shows an example of app-specific settings configuration for a sample app in the server cockpit.

appupdate_mgmt_cockpit

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

Update Flow

  1. The administrator uploads a new archive of the www folder contents to the 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 the Hybrid SDK (Kapsel) required for the update, and the development version (for example, the build version). The 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 the following documentation:

    Mobile Platform

    Documentation

    SAP Mobile Platform Server

    Uploading and Deploying Hybrid Apps

    SAP Cloud Platform mobile service for development and operations

    Uploading and Deploying Hybrid Apps.

  2. The Hybrid SDK (Kapsel) application with the AppUpdate plugin checks with the 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. The 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.
  3. If an update to the native Hybrid SDK (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 the server , the delta of the www folder contents between the on-device and server revision numbers are downloaded to the Hybrid SDK (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 Hybrid SDK (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.
  4. 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 Hybrid SDK (Kapsel) application container, and the new version is loaded.

Example 1: User Accepts App Update

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

Example 2: User Defers Update Action

  1. The AppUpdate function starts and triggers any required log on process.
  2. Checking event is fired by AppUpdate.
  3. AppUpdate finds that an update is available on the server, and the downloading event is fired.
  4. Updates finish downloading.
  5. The sap.AppUpdate.onupdateready function is triggered.
  6. A prompt asks the user to reload the application.
  7. The user cancels the prompt.
  8. 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.  

Example:

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

The 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:
  1. 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.

  2. 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 the 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

Hybrid SDK (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.htmlInformation published on non-SAP site.

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 Hybrid SDK (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 Hybrid SDK (Kapsel) application bundle.  This ensures that the correct value is used.