Namespace: AppUpdate

sap. AppUpdate

Used to provide server-based updates to the application content.

The AppUpdate plugin updates the contents of the www folder of deployed Kapsel applications. After an application successfully does a logon to an SAP Mobile Platform 3 server, the AppUpdate plugin is able to download an available update. See Uploading Hybrid Apps in user documentation for information on how to upload an update to SAP Mobile Platform 3 server.

After an update is completely downloaded, the application user is prompted to install the update and restart the application. They can decline if they wish.

Once an update is installed, the application's revision number is updated.

Adding and Removing the AppUpdate Plugin
The AppUpdate plugin is added and removed using the Cordova CLI.

To add the AppUpdate plugin to your project, use the following command:
cordova plugin add kapsel-plugin-appupdate

To remove the AppUpdate plugin from your project, use the following command:
cordova plugin rm kapsel-plugin-appupdate

Hybrid App Revision Preference
This is an optional preference that tells the AppUdate plugin if the local assets are uploaded to the server, and at what number. If this preference is not provided, the default revision is 0. In your config.xml file you can add the following preference:


This means that the local assets in your www folder are uploaded to the server and the server is reporting revision 1 for them. This allows the application to receive a delta update when revision 2 is available instead of a full update.

Caveats
It is important to test that your update has valid HTML, Javascript, and CSS. Otherwise, the update could prevent the application from functioning correctly, and may no longer be updateable. You can test the updated application in a separate simulator or additional test device. You can also validate your Javascript with tools like JSLint, or JSHint. You can validate CSS with CSS Lint.

Methods

(static) addEventListener(eventname, f)

Add a listener for an AppUpdate event. See events for available event names.
Parameters:
Name Type Description
eventname string Name of the app update event.
f function Function to call when event is fired.
Example
sap.AppUpdate.addEventListener('checking', function(e) {
    console.log("Checking for update");
});

(static) autoCheck(value)

Enables/Disables automatic checks for updates The default value maps to true
Parameters:
Name Type Description
value boolean false to disable automatic update checks.

(static) cancelDownload()

Cancels an update download, if one is in progress.
Example
sap.AppUpdate.cancelDownload();

(static) reloadApp()

Replaces the app resources with any newly downloaded resources.
Example
sap.AppUpdate.reloadApp();

(static) removeEventListener(eventname, f)

Removes a listener for an AppUpdate event. See events for available event names.
Parameters:
Name Type Description
eventname string Name of the app update event.
f function Function that was registered.
Example
// Adding the listener
var listener = function(e) {
    console.log("Checking for update");
});
sap.AppUpdate.addEventListener('checking', listener);

// Removing the listener
sap.AppUpdate.removeEventListener('checking', listener);

(static) reset()

Removes all local updates and loads the original web assets bundled with the app. Call this after delete registration. Reset calls error callback if called during the update process.
Example
sap.logon.Core.deleteRegistration(function() { 
    sap.AppUpdate.reset();
}, function() {});

(static) update()

Force an update check. By default updates are done automatically during logon and resume. See events for what will be fired during this process.
Example
sap.AppUpdate.update();

Events

checking

Event fired when AppUpdate is checking for an update.
Type:
  • object
Properties:
Name Type Description
type string The name of the event. Value will be checking.
Example
sap.AppUpdate.addEventListener('checking', function(e) {
    console.log("Checking for update");
});

downloading

Event fired when AppUpdate has found an update and is starting the download.
Type:
  • object
Properties:
Name Type Description
type string The name of the event. Value will be downloading.
Example
sap.AppUpdate.addEventListener('downloading', function(e) {
    console.log("Downloading update");
});

error

Event fired when AppUpdate encounters an error while checking for an update or downloading an update. The status code and status message are provided with this event.
Type:
  • object
Properties:
Name Type Description
type string The name of the event. Value will be error.
statusCode int The http error code.
statusMessage string The http status message.
Example
sap.AppUpdate.addEventListener('error', function(e) {
    console.log("Error downloading update. statusCode: " + e.statusCode + " statusMessage: " + e.statusMessage);
});

insufficientspace

Event fired when AppUpdate does not have enough space to download or apply an update.
Type:
  • object
Properties:
Name Type Description
type string The name of the event. Value will be insufficientspace.
Example
sap.AppUpdate.addEventListener('insufficientspace', function(e) {
    console.log("No update");
});

noupdate

Event fired when AppUpdate finds no available updates on server.
Type:
  • object
Properties:
Name Type Description
type string The name of the event. Value will be noupdate.
Example
sap.AppUpdate.addEventListener('noupdate', function(e) {
    console.log("No update");
});

progress

Event fired when AppUpdate has made progress downloading the update.
Type:
  • object
Properties:
Name Type Description
type string The name of the event. Value will be progress.
lengthComputable boolean Specifies whether or not the total size is known.
loaded int The number of bytes transferred so far.
total int The total number of bytes of content that will be transferred. If total size is unknown, this value is zero.
Since:
  • 3.0.2
Example
sap.AppUpdate.addEventListener('progress', function(e) {
    if (e.lengthComputable) {
         var percent = Math.round(e.loaded / e.total * 100);
         console.log("Progress " + percent);
    }
});

updateready

Event fired when AppUpdate has a newly downloaded update available. A default handler is already added to sap.AppUpdate.onupdateready that will ask the user to reload the app. When handling this event you should call sap.AppUpdate.reloadApp() to apply the downloaded update.
Type:
  • object
Properties:
Name Type Description
type string The name of the event. Value will be updateready.
revision int The revision that was downloaded.
Example
// This will listen for updateready event.  
// Note: Use sap.AppUpdate.onupdateready if you want to override the default handler.
sap.AppUpdate.addEventListener('updateready', function(e) {
    console.log("Update ready");
});

// Override default handler so that we automatically load the update 
// without first prompting the user for permission,
sap.AppUpdate.onupdateready = function(e) {
    // No notification just reload
    console.log("Apply application update...");
    sap.AppUpdate.reloadApp();
};

// Override default handler with custom prompt to warn the user that the 
// application is ready to update.
sap.AppUpdate.onupdateready = function() {
    console.log("Confirming application update…");
    navigator.notification.confirm('Update Available',
       function(buttonIndex) {
           if (buttonIndex === 2) {
               console.log("Applying application update…");
               sap.AppUpdate.reloadApp();
           }
       }, 
       "Update", ["Later", "Relaunch Now"]);
};

updatetoolargeforcellular

Event fired when the device is connected to a non-WIFI network and the size of the update is greater than the value set with the config.xml preference named appUpdateWifiDownloadLimit. That value is in bytes. For example, to set the limit to 1024 bytes, add the following to config.xml:
Type:
  • object
Properties:
Name Type Description
type string The name of the event. Value will be updatetoolargeforcellular.
Example
sap.AppUpdate.addEventListener('updatetoolargeforcellular', function(e) {
    console.log("No update");
});