For up-to-date product documentation, see the IBM MobileFirst Foundation Developer Center.

Customizing the Direct Update user 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 control the direct update process without presenting a user interface to the user and control what happens when the direct update process fails.

Override the handleDirectUpdate function of the Direct Update challenge handler to customize the direct update process and interface in iOS and Android applications. The handleDirectUpdate function is defined inside worklights.js. It has the following format:

wl_directUpdateChallengeHandler.handleDirectUpdate = function (directUpdateData,directUpdateContext){...}

The function accepts the following arguments:

directUpdateData

A JSON object that contains 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 a .start() and .stop() function 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 invokes the wl_directUpdateChallengeHandler.handleDirectUpdate function.

The function provides a default Direct Update design: 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 Default Direct Update user interface. We can implement custom Direct Update user interface behavior or customize the Direct Update dialog box by overriding this function and implementing your own logic.

The following example handleDirectUpdate function implements a custom message in the Direct Update dialog. Add this code into the www/js/index.js file of the Cordova project .

wl_directUpdateChallengeHandler.handleDirectUpdate = function(directUpdateData, directUpdateContext) {        
    navigator.notification.confirm(  // Creates a dialog.
        'Custom dialog body text',
        // Handle dialog buttons.
          directUpdateContext.start();
        },
        'Custom dialog title text',
        ['Update']
    );
};

The result is shown in Figure 1.

Figure 1. Custom update notice

We can start the direct update process by running the directUpdateContext.start() method whenever the user clicks the dialog button. The default progress screen, which resembles the one in previous versions of MobileFirst Server is shown.

This method supports the following types of invocation:

• When no parameters are specified, IBM MobileFirst™ Platform Server uses the default progress screen.
• 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:

  Table 1. Status codes for the onFinish rule

  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 you 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. You 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: Running 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 that you 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);
};

Note: When the application is sent to the background, the direct-update process is suspended.

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 that 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 by 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: Update Cordova client apps directly