Using Direct Update to quickly update your application

improve this page | report issue

About Direct Update

With Direct Update, hybrid applications (for the Android, iOS, and Windows Phone 8 environments) can be updated "over-the-air" with updated/refreshed versions of the web resources.

This tutorial covers the following topics:

Benefits and restrictions


  • Using Direct Update, organizations can ensure that users always use the latest version of the application.
  • Application versions are better controlled. Users are notified of pending updates or prevented from using obsolete versions.
  • Updates that are deployed to the MobileFirst Server are automatically pushed to user devices.
  • Updates can be pushed silently without user interaction. This benefit requires that you create a custom Direct Update (see Customizing the UI).


  • The update is for the app web resources only.
  • To update native resources, a new app version must be uploaded to the respective app store.
  • Android: no restrictions.
  • Windows Phone 8: no restrictions.
  • iOS:
    • B2C: according to the terms of service of your company; usually at least bug fixes are allowed.
    • B2E: through the iOS Developer Enterprise Program

Under the hood

Direct Update is based on the MobileFirst Authentication Framework. It comes with a predefined authentication realm and challenge handler, and can be adjusted in the authenticationConfig.xml file to the following modes:

  • perSession
  • perRequest
  • disabled

The UI & UX of the Direct Update process can be fully customized by using simple interfaces.

Server-side customization

By default, the mobileSecurityTest has Direct Update enabled in perSession mode:

<mobileSecurityTest name="mobileTests">
    <testDeviceId provisioningType="none" />
    <testUser realm="myMobileLoginForm" />
    <testDirectUpdate mode="perSession" />

To disable Direct Update, change its mode to disabled, and similarly to override it to other modes.

<testDirectUpdate mode="disabled" /> 

By default, the customSecurityTest does not have any realms.
To add a Direct Update realm to a custom security test, add a test element with the realm name wl_directUpdateRealm and define the required mode property:

<customSecurityTest name="customTests">
    <test realm="wl_directUpdateRealm" mode="perRequest"/>

For more information, see the topic about Direct Update as a security realm, in the user documentation.

Internal function - How Direct Update works

The application web resources are initially packaged with the application to ensure first offline availability. Afterwards, the application checks for updates based on available configurations (per session or per request, as explained above).

The updated web resources are downloaded when necessary.
After a Direct Update, the application no longer uses prepackaged resources but those resources in the application's sandbox.


User experience

Default behavior

  1. By default, after a Direct Update is received, a dialog is displayed and the user is asked whether to begin the update process.
  2. After the user approves, a progress bar dialog is displayed and web resources are downloaded.
  3. The application is automatically reloaded after the update is complete.


Differential direct update

With this feature, it is no longer necessary for the client application to download the entire web resources on every update. Instead, only the resources that were changed are downloaded and updated. This reduces download time, conserves bandwidth, and improves overall user experience.

Important: A differential update is possible only if the client application's web resources are one version behind the application that is currently deployed on the server. Client applications that are more than one version behind the current deployed application (the application was deployed to the server at least twice since the client application was updated), receive a full update, meaning that the entire web resources are downloaded and updated.

There is no change in the behaviour of applications that were built with previous versions of IBM MobileFirst Platform Foundation.

Customizing the UI

It is possible to override the default UI and/or UX and create a custom Direct Update behavior altogether.

To do so, override the handleDirectUpdate function:

wl_DirectUpdateChallengeHandler.handleDirectUpdate = function(directUpdateData, directUpdateContext) {
    // custom Direct Update logic

  • directUpdateData - A JSON object containing the downloadSize property that represents the file size (in bytes) of the update package to be downloaded from MobileFirst Server.
  • directUpdateContext - A JavaScript object exposing the .start() and .stop() functions, which start and stop the Direct Update flow.


In the example code below, a custom Direct Update dialog is presented for the user to either continue with the update process or dismiss it.
Examples of a new customized Direct Update UI:

  • A WL.SimpleDialog
  • A dialog that is created by using a third-party JavaScript framework (such as Dojo or jQuery Mobile)
  • Fully native UI by executing a Cordova plug-in
  • An alternate HTML file that is presented to the user with options
  • And so on…

wl_directUpdateChallengeHandler.handleDirectUpdate = function(directUpdateData,
directUpdateContext) {
    // custom WL.SimpleDialog for Direct Update
    var customDialogTitle = 'Custom Title Text';
    var customDialogMessage = 'Custom Message Text';
    var customButtonText1 = 'Update Application';
    var customButtonText2 = 'Not Now';, customDialogMessage,
            text : customButtonText1,
            handler : function() {
            text : customButtonText2,
            handler : function() {


In the example above, the submitFailure API is used to dismiss the Direct Update:


As mentioned, when the developer creates a customized Direct Update experience, the responsibility for its flow now belongs to the developer.

As such, it is important to call submitFailure() to notify the MobileFirst framework that the process completed with a "failure". The MobileFirst framework in turn invokes the onFailure callback of the invocation that triggered the Direct Update.

Because the update process did not take place, it will occur again the next time it is triggered.

Optionally, a developer can also supply a Direct Update listener to fully control a Direct Update lifecycle. For more information, see the topic about customizing the direct update interface, in the user documentation.


Distribution - Working with Direct Update in the field


(*) During development cycles, testers automatically get recent web resources through internal distribution mechanisms and not through application stores.

Disabling old application versions

From the MobileFirst Operations Console, it is possible to prevent users from using obsolete versions and to notify users about available updates.

Clarification: The Remote Disable feature only prevents users from interacting with MobileFirst Server; that is, it prevents the app from connecting to the server. The application itself is still accessible. Any action in the application that requires server connectivity is blocked.

Direct Update authenticity

Enabling Direct Update authenticity prevents a 3rd-party attacker from altering the transmitted web resources from the server to the client application (that is, when it is cached in a content delivery network (CDN)).

To enable Direct Update authenticity:

  1. Generate a certificate and place it in the MobileFirst project in the server\conf folder.
  2. Edit the MobileFirst Default Certificate section in server\conf\ with the certificate keystore information, for example:
  3. Add the certificate public key using the Application Descriptor Design view. To do so:
    1. Right-click the application folder and select Extract Public Signing Key.
    2. Follow the on-screen instructions.
  4. missing_alt

    You can find the public key on the Design view of the Application Descriptor Editor.


    You can also find the public key on the Source view of the Application Descriptor Editor.

          public keystore value


  • It is highly suggested to enable Secure Direct Update.
  • Secure Direct Update does not work on already-deployed applications.
  • Secure Direct Update works on applications published with the above configuration.

For more information, see the topic about configuring and customizing direct update, in the user documentation.

Sample application

Click to download the Studio project.

Last modified on November 09, 2016