Customize the direct update interface and process

Customize the direct update interface and process

We can change the default user interface for the direct update dialog boxes and the messages that are displayed to the user. We can also control when an application checks for a direct update, run the direct update process without presenting a user interface to the user, link the checking for available direct updates to a call to an adapter, and control what happens when the direct update process fails.
Use the handleDirectUpdate function of the direct update challenge handler to customize the direct update process and interface on iOS, Android, and Windows Phone 8. The handleDirectUpdate function has the following format:
wl_directUpdateChallengeHandler.handleDirectUpdate = function (directUpdateData,directUpdateContext){...}

The function accepts the following arguments:

directUpdateData

A JSON object containing the downloadSize property that represents the files size in bytes of the update package to be downloaded from server.

directUpdateContext

A JavaScript object that exposes .start() and .stop() functions that start and stop the direct update flow.

If the web resources are newer on the MobileFirst Server than in the application, direct update challenge data is added to the server response. Whenever the MobileFirst client-side framework detects this direct update challenge, it starts the wl_directUpdateChallengeHandler.handleDirectUpdate function.
The function provides a default direct update look and feel: a default message dialog that is displayed when a direct update is available and a default progress screen that is displayed when the direct update process is initiated. For examples of default screens, see Direct updates of app versions to mobile devices. We can implement custom direct update user interface behavior or customize the direct update dialog box by overriding this function and implementing our own logic.
The following example handleDirectUpdate function implements a custom message in the direct update dialog:
wl_directUpdateChallengeHandler.handleDirectUpdate = function(directUpdateData,directUpdateContext) {
  var customDialogTitle = 'Custom Title Text';
  var customDialogMessage = 'Custom Message Text';
  var customButtonText = 'Custom Button Text';
  WL.SimpleDialog.show(customDialogTitle, customDialogMessage, [{
    text : customButtonText, handler : function() {
      directUpdateContext.start();
    }
  }]);
};
We can start the direct update process by running the directUpdateContext.start() method whenever the user clicks the pop-up dialog button. This method supports the following types of invocation:

When no parameters are specified, MPF uses the default progress screen, which resembles the one in IBM Worklight v6.1.0.

When a listener function such as directUpdateContext.start(directUpdateCustomListener) is supplied, the direct update process runs in the background while the process sends lifecycle events to the listener. The custom listener must implement the following methods:
var directUpdateCustomListener = {
  onStart: function(totalSize){
  },   onProgress: function(status,totalSize,completedSize){
  },   onFinish: function(status){
};
The listener methods are started during the direct update process according to following rules:

onStart is called with the totalSize parameter that holds the size of the update file.

onProgress is called multiple times with status DOWNLOAD_IN_PROGRESS, totalSize, and completedSize (the volume that is downloaded so far).

onProgress is called with status UNZIP_IN_PROGRESS.

onFinish is called with one of the following final status codes:

Status code Description
SUCCESS Direct update finished with no errors.
CANCELED Direct update was canceled (for example, because the stop() method was called).
FAILURE_NETWORK_PROBLEM There was a problem with a network connection during the update.
FAILURE_DOWNLOADING The file was not downloaded completely.
FAILURE_NOT_ENOUGH_SPACE There is not enough space on the device to download and unpack the update file.
FAILURE_UNZIPPING There was a problem unpacking the update file.
FAILURE_ALREADY_IN_PROGRESS The start method was called while direct update was already running.
FAILURE_INTEGRITY Authenticity of update file cannot be verified.
FAILURE_UNKNOWN Unexpected internal error.

If we implement a custom direct update listener, we must ensure that the app is reloaded when the direct update process is complete and the onFinish() method has been called. We must also call wl_directUpdateChalengeHandler.submitFailure() if the direct update process fails to complete successfully.
The following example shows an implementation of a custom direct update listener:
var directUpdateCustomListener = {
  onStart: function(totalSize){
    //show custom progress dialog   },   onProgress: function(status,totalSize,completedSize){
    //update custom progress dialog   },   onFinish: function(status){
    if (status == 'SUCCESS'){
      //show success message
      WL.Client.reloadApp();
    }
    else {
      //show custom error message
      //submitFailure must be called is case of error
      wl_directUpdateChallengeHandler.submitFailure();
    }
};
wl_directUpdateChallengeHandler.handleDirectUpdate = function(directUpdateData, directUpdateContext){
  WL.SimpleDialog.show('Update Avalible', 'Press update button to download version 2.0', [{
    text : 'update', handler : function() {
      directUpdateContext.start(directUpdateCustomListener);
    }
  }]);
};
Scenario: Run UI-less direct updates

IBM MobileFirst Platform Foundation supports UI-less direct update when the application is in the foreground.
To run UI-less direct updates, implement directUpdateCustomListener. Provide empty function implementations to the onStart and onProgress methods. Empty implementations cause the direct update process to run in the background.
To complete the direct update process, the application must be reloaded. The following options are available:

The onFinish method can be empty as well. In this case, direct update will apply after the application has restarted.

We can implement a custom dialog that informs or requires the user to restart the application. (See the following example.)

The onFinish method can enforce a reload of the application by calling WL.Client.reloadApp().

Here is an example implementation of directUpdateCustomListener:
var directUpdateCustomListener = {
  onStart: function(totalSize){
  },   onProgress: function(status,totalSize,completeSize){
  },   onFinish: function(status){
    WL.SimpleDialog.show('New Update Available', 'Press reload button to update to new version', [ {
      text : WL.ClientMessages.reload,   handler : WL.Client.reloadApp
    }]);
};
Implement the wl_directUpdateChallengeHandler.handleDirectUpdate function. Pass the directUpdateCustomListener implementation we have created as a parameter to the function. Make sure directUpdateContext.start(directUpdateCustomListener) is called. Here is an example wl_directUpdateChallengeHandler.handleDirectUpdate implementation:
wl_directUpdateChallengeHandler.handleDirectUpdate = function(directUpdateData, directUpdateContext){
  directUpdateContext.start(directUpdateCustomListener);
};
When the application is sent to the background, the direct-update process is suspended.

Scenario: Triggering direct updates on demand

By default, the application checks for direct updates once per session. We can program the application to check for direct updates at a different point in time, for example, we can trigger a check for direct updates whenever a user clicks a button.
The mobile security test provided by default (in authenticationConfig.xml.under the server/conf folder) contains a direct update security test. We must disable this test to trigger direct update on demand. For example:
Custom security test:
<customSecurityTest name="customNoDirectUpdate">
  <test realm="wl_anonymousUserRealm" isInternalUserID="true" step="1"/>
  <test realm="wl_deviceNoProvisioningRealm" isInternalDeviceID="true" step="2"/>
</customSecurityTest>
Mobile security test:
<mobileSecurityTest name="mobileTests">
  <testDeviceId provisioningType="none" />
  <testUser realm="wl_anonymousUserRealm" />
</mobileSecurityTest>
In the JavaScript code, when you decided to run direct update (for example, through a WiFi connection or when the application is in the background) call WL.Client.checkForDirectUpdate(). This call triggers direct update on demand.

Scenario: Checking for direct updates when a specific adapter is called

This scenario shows how we can link the checking for direct updates to adapter calls.
Program the application to use a custom security test without direct update. The following example shows such a custom security test in authenticationConfig.xml.
<customSecurityTest name="customNoDirectUpdate">
  <test realm="wl_anonymousUserRealm" isInternalUserID="true" step="1"/>
  <test realm="wl_deviceNoProvisioningRealm" isInternalDeviceID="true" step="2"/>
</customSecurityTest>
Program the adapter to use a custom security test with direct update defined. The following example shows such a custom security test in authenticationConfig.xml.
<customSecurityTest name="customWithDirectUpdateRequest">
  <test realm="wl_directUpdateRealm" mode="perRequest"/>
  <test realm="wl_anonymousUserRealm" isInternalUserID="true" step="1"/>
  <test realm="wl_deviceNoProvisioningRealm" isInternalDeviceID="true" step="2"/>
</customSecurityTest>
In this case, the application does not require direct update even if it is available on the server until the adapter is called from the JavaScript code as shown in the following example:
WL.Client.invokeProcedure({adapter : 'RSSReader', procedure : 'getFeeds'});

Scenario: Handling a direct update failure

This scenario shows how to handle a direct update failure that might be caused, for example, by loss of connectivity. In this scenario, the user is prevented from using the app even in offline mode. A dialog is displayed offering the user the option to try again.
Create a global variable to store the direct update context so we can use it subsequently when the direct update process fails. For example:
var savedDirectUpdateContext;

Implement a direct update challenge handler. Save the direct update context here. For example:
wl_directUpdateChallengeHandler.handleDirectUpdate = function(directUpdateData, directUpdateContext){
  savedDirectUpdateContext = directUpdateContext; // save direct update context   var downloadSizeInMB = (directUpdateData.downloadSize / 1048576).toFixed(1).replace(".", WL.App.getDecimalSeparator());
  var directUpdateMsg = WL.Utils.formatString(WL.ClientMessages.directUpdateNotificationMessage, downloadSizeInMB);
  WL.SimpleDialog.show(WL.ClientMessages.directUpdateNotificationTitle, directUpdateMsg, [{
    text : WL.ClientMessages.update, handler : function() {
      directUpdateContext.start(directUpdateCustomListener);
    }
  }]);
};
Create a function that starts the direct update process using the direct update context. For example:
restartDirectUpdate = function () {
  savedDirectUpdateContext.start(directUpdateCustomListener); // use saved direct update context to restart direct update };
Implement directUpdateCustomListener. Add status checking in the onFinish method. If the status starts with "FAILURE", open a modal only dialog with the option "Try Again". For example:
var directUpdateCustomListener = {
  onStart: function(totalSize){
    alert('onStart: totalSize = ' + totalSize + 'Byte');
  },   onProgress: function(status,totalSize,completeSize){
    alert('onProgress: status = ' + status + ' completeSize = ' + completeSize + 'Byte');
  },   onFinish: function(status){
    alert('onFinish: status = ' + status);
    var pos = status.indexOf("FAILURE");
    if (pos > -1) {
      WL.SimpleDialog.show('Update Failed', 'Press try again button', [ {
        text : "Try Again",     handler : restartDirectUpdate // restart direct update       }]);
    }
};
When the user clicks the Try Again button, the application restarts the direct update process.

Parent topic: Configure and customizing direct update

Status code	Description
SUCCESS	Direct update finished with no errors.
CANCELED	Direct update was canceled (for example, because the stop() method was called).
FAILURE_NETWORK_PROBLEM	There was a problem with a network connection during the update.
FAILURE_DOWNLOADING	The file was not downloaded completely.
FAILURE_NOT_ENOUGH_SPACE	There is not enough space on the device to download and unpack the update file.
FAILURE_UNZIPPING	There was a problem unpacking the update file.
FAILURE_ALREADY_IN_PROGRESS	The start method was called while direct update was already running.
FAILURE_INTEGRITY	Authenticity of update file cannot be verified.
FAILURE_UNKNOWN	Unexpected internal error.