Using Direct Update to quickly update your application
About Direct Update
With Direct Update, hybrid applications (for the Android, iOS, and Windows Phone 8 environments) and Cordova-based applications can be updated "over-the-air" with updated/refreshed versions of the web resources.
This tutorial covers the following topics:
- Benefits and restrictions
- Under the hood
- Internal function - How Direct Update works
- User experience
- Distribution - Working with Direct Update in the field
- Disabling old application versions
- Direct Update authenticity
- Sample application
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.
- 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 hoodDirect Update is based on the MobileFirst Authentication Framework. It comes with a predefined authentication realm and challenge handler, and can be adjusted in the following ways:
- The security test can be disabled, and instead be explicitly called using the
- Change the
wl.realm.expiration.directUpdatevalue in the
worklight.propertiesfile to a lower value. Note: The lower the value, the more network traffic will incur. The value should be configured with care.
- If the applicaiton accesses a resource that is protected by OAuth authentication, and the client has a valid token, the MobileFirst Server is not called. As a result, the server does not check for an available Direct Update, regardless of the value of the mode property (explained further below). The MobileFirst Server is called when the token expires or when the Direct Update realm inside the token expires. When the realm expires, the Direct Update authenticator is invoked and the server checks for an available Direct Update.
- For more information on configuring the Direct Update review the "Configuring login modules" user documentation topic.
By default, the
mobileSecurityTest has Direct Update enabled in
It can also be configured to
perRequest however do review the notes above in case using OAuth.
To disable Direct Update, change its mode to
disabled, and similarly to override it to other modes.
Also 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:
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.
- By default, after a Direct Update is received, a dialog is displayed and the user is asked whether to begin the update process.
- After the user approves, a progress bar dialog is displayed and web resources are downloaded.
- 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
directUpdateData- A JSON object containing the
downloadSizeproperty that represents the file size (in bytes) of the update package to be downloaded from MobileFirst Server.
.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
- Fully native UI by executing a Cordova plug-in
- An alternate HTML file that is presented to the user with options
- And so on…
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:
- Generate a certificate and place it in the MobileFirst project in the
- Edit the MobileFirst Default Certificate section in
server\conf\worklight.propertieswith the certificate keystore information, for example:
- Add the certificate public key using the Application Descriptor Design view. To do so:
- Right-click the application folder and select Extract Public Signing Key.
- Follow the on-screen instructions.
The public key can then be found in the Application Descriptor Design view:
The public key can also be found in the Application Descriptor Editor view:
- 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.
Click to download the MobileFirst project.▲
Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.