Upgrade the WebView

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

Upgrade the WebView

IBM MobileFirst™ Platform Foundation V8.0.0 Cordova SDK (JavaScript) introduced numerous changes that require adaptations of your code.
The manual migration process involves a few stages:
Create a new Cordova MobileFirst project
Replacing the necessary web resource elements with the code from your previous version
Making the necessary changes to our JavaScript code to conform to SDK changes

Many MobileFirst API elements were removed in V8.0.0. Removed elements are clearly marked as non-existent in an IDE that supports autocorrect for JavaScript.
For more information about IDEs for editing JavaScript with autocomplete, see Editing WebView (JavaScript) code.
Table 1 lists those API elements that require removal, with suggestions on how to replace the functionality. Many of the removed elements are UI elements that can be replaced with Cordova plug-ins or HTML 5 elements. Some methods have changed.
For examples of some sample code for creating the client and accessing the server with the new V8.0.0 client for JavaScript, see Some initial WebView code for connecting to the server.
Table 1. Discontinued JavaScript UI elements
API element Migration path

WL.BusyIndicator
WL.OptionsMenu
WL.TabBar
WL.TabBarItem
Use Cordova plug-ins or HTML 5 elements.
WL.App.close() Handle this event outside of MobileFirst.
WL.App.copyToClipboard() Use Cordova plug-ins providing this functionality.
WL.App.openUrl(url, target, options) Use Cordova plug-ins providing this functionality.
Note: For your information, the Cordova InAppBrowser plug-in provides this feature..

WL.App.overrideBackButton(callback)
WL.App.resetBackButton()
Use Cordova plug-ins providing this functionality.
Note: For your information, the Cordova backbutton plug-in provides this feature..

WL.App.getDeviceLanguage()
Use Cordova plug-ins providing this functionality.
Note: For your information, the Cordova cordova-plugin-globalization plug-in provides this feature.

WL.App.getDeviceLocale()
Use Cordova plug-ins providing this functionality.
Note: For your information, the Cordova cordova-plugin-globalization plug-in provides this feature.
WL.App.BackgroundHandler To run a custom handler function, use the standard Cordova pause event listener. Use a Cordova plug-in that provides privacy and prevents iOS and Android systems and users from taking snapshots or screen captures. For more information, see the description of the PrivacyScreenPlugin at https://github.com/devgeeks/PrivacyScreenPlugin.

WL.Client.close()
WL.Client.restore()
WL.Client.minimize()
The functions were provided to support the Adobe AIR platform, which is not supported by IBM MobileFirst Platform V8.0.0.
WL.Toast.show(string) Use Cordova plug-ins for Toast.

Table 2. Other Discontinued JavaScript elements
API Migration path
WL.Client.checkForDirectUpdate(options) No replacement.
Note: We can call WLAuthorizationManager.obtainAccessToken to trigger a direct update if one is available. The access to a security token triggers a direct update if one is available on the server. But we cannot trigger Direct Update on demand. For more information about customizing the Direct Update user interface and process, see Customizing the Direct Update user interface and process.
WL.Client.setSharedToken({key: myName, value: myValue})
WL.Client.getSharedToken({key: myName})
WL.Client.clearSharedToken({key: myName})
No replacement.
WL.Client.isConnected()
connectOnStartup init option
Use WLAuthorizationManager.obtainAccessToken to check connectivity to the server and apply application management rules.
WL.Client.setUserPref(key,value, options)
WL.Client.setUserPrefs(userPrefsHash, options)
WL.Client.deleteUserPrefs(key, options)
No replacement. We can use an adapter and the MFP.Server.getAuthenticatedUser API to manage user preferences.
WL.Client.getUserInfo(realm, key)
WL.Client.updateUserInfo(options)
No replacement.
WL.Client.logActivity(activityType) Use WL.Logger. For more information, see Logger SDK.
WL.Client.login(realm, options) Use WLAuthorizationManager.login. To get started with authentication and security, see the Authentication and Security tutorials.
WL.Client.logout(realm, options) Use WLAuthorizationManager.logout.
WL.Client.obtainAccessToken(scope, onSuccess, onFailure) Use WLAuthorizationManager.obtainAccessToken.
WL.Client.transmitEvent(event, immediate)
Wl.Client.purgeEventTransmissionBuffer()
Wl.Client.setEventTransmissionPolicy(policy)
Create a custom adapter for receiving notifications of these events.

WL.Device.getContext()
WL.Device.startAcquisition(policy, triggers, onFailure)
WL.Device.stopAcquisition()
WL.Device.Wifi
WL.Device.Geo.Profiles
WL.Geo
Use native API or third-party Cordova plug-ins for GeoLocation.
WL.Client.makeRequest (url, options) Create a custom adapter that provides the same functionality
WLDevice.getID(options) Use Cordova plug-ins providing this functionality.
Note: For your information, device.uuid from the cordova-plugin-device plug-in provides this feature.
WL.Device.getFriendlyName() Use WL.Client.getDeviceDisplayName
WL.Device.setFriendlyName() Use WL.Client.setDeviceDisplayName
WL.Device.getNetworkInfo(callback) Use Cordova plug-ins providing this functionality.
Note: For your information, the cordova-plugin-network-information plug-in provides this feature.
WLUtils.wlCheckReachability() Create a custom adapter to check server availability.

WL.EncryptedCache
Use JSONStore to store encrypted data locally. JSONStore is in the cordova-plugin-mfp-jsonstore plug-in. For more information, see JSONStore.
WL.SecurityUtils.remoteRandomString(bytes) Create a custom adapter that provides the same functionality.
WL.Client.getAppProperty(property) We can retrieve the app version property by using the cordova plugin add cordova-plugin-appversion plug-in. The version that is returned is the native app version (Android and iOS only).
WL.Client.Push.* Use JavaScript client-side push API from the cordova-plugin-mfp-push plug-in. For more information, see Migrating to push notifications from event source-based notifications.
WL.Client.Push.subscribeSMS(alias, adapterName, eventSource, phoneNumber, options) Use MFPPush.registerDevice(org.json.JSONObject options, MFPPushResponseListener listener) to register the device for push and SMS.
WLAuthorizationManager.obtainAuthorizationHeader(scope) Use WLAuthorizationManager.obtainAccessToken to obtain a token for the required scope. For more information about implementing a custom resource request, see JavaScript custom resource-request implementation sample.
WLClient.getLastAccessToken(scope) Use WLAuthorizationManager.obtainAccessToken
WLClient.getLoginName()
WL.Client.getUserName(realm)
No replacement
WL.Client.getRequiredAccessTokenScope(status, header) Use WLAuthorizationManager.isAuthorizationRequired and WLAuthorizationManager.getResourceScope.
WL.Client.isUserAuthenticated(realm) No replacement
WLUserAuth.deleteCertificate(provisioningEntity) No replacement
WL.Trusteer.getRiskAssessment(onSuccess, onFailure) No replacement
WL.Client.createChallengeHandler(realmName) To create a challenge handler for handling custom gateway challenges, use WL.Client.createGatewayChallengeHandler(gatewayName). To create a challenge handler for handling MobileFirst security-check challenges, use WL.Client.createSecurityCheckChallengeHandler(securityCheckName). For more information about the V8.0.0 challenge-handler APIs, see Client security APIs.
WL.Client.createWLChallengeHandler(realmName) Use WL.Client.createSecurityCheckChallengeHandler(securityCheckName). For more information about the V8.0.0 challenge-handler APIs, see Client security APIs.
challengeHandler.isCustomResponse() where challengeHandler is a challenge-handler object that is returned by WL.Client.createChallengeHandler() Use gatewayChallengeHandler.canHandleResponse() where gatewayChallengeHandler is a challenge-handler object that is returned by WL.Client.createGatewayChallengeHandler().
wlChallengeHandler.processSucccess() where wlChallengeHandler is a challenge-handler object that is returned by WL.Client.createWLChallengeHandler() Use securityCheckChallengeHandler.handleSuccess() where securityCheckChallengeHandler is a challenge-handler object that is returned by WL.Client.createSecurityCheckChallengeHandler().
WL.Client.AbstractChallengeHandler.submitAdapterAuthentication() Implement similar logic in your challenge handler. For custom gateway challenge handlers, use a challenge-handler object that is returned by WL.Client.createGatewayChallengeHandler(). For MobileFirst security-check challenge handlers, use a challenge-handler object that is returned by WL.Client.createSecurityCheckChallengeHandler().
WL.Client.AbstractChallengeHandler.submitFailure(err) Use WL.Client.AbstractChallengeHandler.cancel().
WL.Client.createProvisioningChallengeHandler() No replacement. Device provisioning is now handled automatically by the security framework.

Table 3. Deprecated JavaScript APIs
API Migration path

WLClient.invokeProcedure(WLProcedureInvocationData invocationData,WLResponseListener responseListener)
WL.Client.invokeProcedure(invocationData, options)
WLClient.invokeProcedure(WLProcedureInvocationData invocationData, WLResponseListener responseListener, WLRequestOptions requestOptions)
WLProcedureInvocationResult

Use the WLResourceRequest instead.
Note: The implementation of invokeProcedure uses WLResourceRequest.
WLClient.getEnvironment Use Cordova plug-ins providing this functionality.
Note: For your information, the device.platform plug-in provides this feature.
WLClient.getLanguage Use Cordova plug-ins providing this functionality.
Note: For your information, the cordova-plugin-globalization plug-in provides this feature.
WL.Client.connect(options) Use WLAuthorizationManager.obtainAccessToken to check connectivity to the server and apply application management rules.

Parent topic: Migrating existing Cordova and hybrid applications


API element	Migration path
WL.BusyIndicator WL.OptionsMenu WL.TabBar WL.TabBarItem	Use Cordova plug-ins or HTML 5 elements.
WL.App.close()	Handle this event outside of MobileFirst.
WL.App.copyToClipboard()	Use Cordova plug-ins providing this functionality.
WL.App.openUrl(url, target, options)	Use Cordova plug-ins providing this functionality. Note: For your information, the Cordova InAppBrowser plug-in provides this feature..
WL.App.overrideBackButton(callback) WL.App.resetBackButton()	Use Cordova plug-ins providing this functionality. Note: For your information, the Cordova backbutton plug-in provides this feature..
WL.App.getDeviceLanguage()	Use Cordova plug-ins providing this functionality. Note: For your information, the Cordova cordova-plugin-globalization plug-in provides this feature.
WL.App.getDeviceLocale()	Use Cordova plug-ins providing this functionality. Note: For your information, the Cordova cordova-plugin-globalization plug-in provides this feature.
WL.App.BackgroundHandler	To run a custom handler function, use the standard Cordova pause event listener. Use a Cordova plug-in that provides privacy and prevents iOS and Android systems and users from taking snapshots or screen captures. For more information, see the description of the PrivacyScreenPlugin at https://github.com/devgeeks/PrivacyScreenPlugin.
WL.Client.close() WL.Client.restore() WL.Client.minimize()	The functions were provided to support the Adobe AIR platform, which is not supported by IBM MobileFirst Platform V8.0.0.
WL.Toast.show(string)	Use Cordova plug-ins for Toast.


API	Migration path
WL.Client.checkForDirectUpdate(options)	No replacement. Note: We can call WLAuthorizationManager.obtainAccessToken to trigger a direct update if one is available. The access to a security token triggers a direct update if one is available on the server. But we cannot trigger Direct Update on demand. For more information about customizing the Direct Update user interface and process, see Customizing the Direct Update user interface and process.
WL.Client.setSharedToken({key: myName, value: myValue}) WL.Client.getSharedToken({key: myName}) WL.Client.clearSharedToken({key: myName})	No replacement.
WL.Client.isConnected() connectOnStartup init option	Use WLAuthorizationManager.obtainAccessToken to check connectivity to the server and apply application management rules.
WL.Client.setUserPref(key,value, options) WL.Client.setUserPrefs(userPrefsHash, options) WL.Client.deleteUserPrefs(key, options)	No replacement. We can use an adapter and the MFP.Server.getAuthenticatedUser API to manage user preferences.
WL.Client.getUserInfo(realm, key) WL.Client.updateUserInfo(options)	No replacement.
WL.Client.logActivity(activityType)	Use WL.Logger. For more information, see Logger SDK.
WL.Client.login(realm, options)	Use WLAuthorizationManager.login. To get started with authentication and security, see the Authentication and Security tutorials.
WL.Client.logout(realm, options)	Use WLAuthorizationManager.logout.
WL.Client.obtainAccessToken(scope, onSuccess, onFailure)	Use WLAuthorizationManager.obtainAccessToken.
WL.Client.transmitEvent(event, immediate) Wl.Client.purgeEventTransmissionBuffer() Wl.Client.setEventTransmissionPolicy(policy)	Create a custom adapter for receiving notifications of these events.
WL.Device.getContext() WL.Device.startAcquisition(policy, triggers, onFailure) WL.Device.stopAcquisition() WL.Device.Wifi WL.Device.Geo.Profiles WL.Geo	Use native API or third-party Cordova plug-ins for GeoLocation.
WL.Client.makeRequest (url, options)	Create a custom adapter that provides the same functionality
WLDevice.getID(options)	Use Cordova plug-ins providing this functionality. Note: For your information, device.uuid from the cordova-plugin-device plug-in provides this feature.
WL.Device.getFriendlyName()	Use WL.Client.getDeviceDisplayName
WL.Device.setFriendlyName()	Use WL.Client.setDeviceDisplayName
WL.Device.getNetworkInfo(callback)	Use Cordova plug-ins providing this functionality. Note: For your information, the cordova-plugin-network-information plug-in provides this feature.
WLUtils.wlCheckReachability()	Create a custom adapter to check server availability.
WL.EncryptedCache	Use JSONStore to store encrypted data locally. JSONStore is in the cordova-plugin-mfp-jsonstore plug-in. For more information, see JSONStore.
WL.SecurityUtils.remoteRandomString(bytes)	Create a custom adapter that provides the same functionality.
WL.Client.getAppProperty(property)	We can retrieve the app version property by using the cordova plugin add cordova-plugin-appversion plug-in. The version that is returned is the native app version (Android and iOS only).
WL.Client.Push.*	Use JavaScript client-side push API from the cordova-plugin-mfp-push plug-in. For more information, see Migrating to push notifications from event source-based notifications.
WL.Client.Push.subscribeSMS(alias, adapterName, eventSource, phoneNumber, options)	Use MFPPush.registerDevice(org.json.JSONObject options, MFPPushResponseListener listener) to register the device for push and SMS.
WLAuthorizationManager.obtainAuthorizationHeader(scope)	Use WLAuthorizationManager.obtainAccessToken to obtain a token for the required scope. For more information about implementing a custom resource request, see JavaScript custom resource-request implementation sample.
WLClient.getLastAccessToken(scope)	Use WLAuthorizationManager.obtainAccessToken
WLClient.getLoginName() WL.Client.getUserName(realm)	No replacement
WL.Client.getRequiredAccessTokenScope(status, header)	Use WLAuthorizationManager.isAuthorizationRequired and WLAuthorizationManager.getResourceScope.
WL.Client.isUserAuthenticated(realm)	No replacement
WLUserAuth.deleteCertificate(provisioningEntity)	No replacement
WL.Trusteer.getRiskAssessment(onSuccess, onFailure)	No replacement
WL.Client.createChallengeHandler(realmName)	To create a challenge handler for handling custom gateway challenges, use WL.Client.createGatewayChallengeHandler(gatewayName). To create a challenge handler for handling MobileFirst security-check challenges, use WL.Client.createSecurityCheckChallengeHandler(securityCheckName). For more information about the V8.0.0 challenge-handler APIs, see Client security APIs.
WL.Client.createWLChallengeHandler(realmName)	Use WL.Client.createSecurityCheckChallengeHandler(securityCheckName). For more information about the V8.0.0 challenge-handler APIs, see Client security APIs.
challengeHandler.isCustomResponse() where challengeHandler is a challenge-handler object that is returned by WL.Client.createChallengeHandler()	Use gatewayChallengeHandler.canHandleResponse() where gatewayChallengeHandler is a challenge-handler object that is returned by WL.Client.createGatewayChallengeHandler().
wlChallengeHandler.processSucccess() where wlChallengeHandler is a challenge-handler object that is returned by WL.Client.createWLChallengeHandler()	Use securityCheckChallengeHandler.handleSuccess() where securityCheckChallengeHandler is a challenge-handler object that is returned by WL.Client.createSecurityCheckChallengeHandler().
WL.Client.AbstractChallengeHandler.submitAdapterAuthentication()	Implement similar logic in your challenge handler. For custom gateway challenge handlers, use a challenge-handler object that is returned by WL.Client.createGatewayChallengeHandler(). For MobileFirst security-check challenge handlers, use a challenge-handler object that is returned by WL.Client.createSecurityCheckChallengeHandler().
WL.Client.AbstractChallengeHandler.submitFailure(err)	Use WL.Client.AbstractChallengeHandler.cancel().
WL.Client.createProvisioningChallengeHandler()	No replacement. Device provisioning is now handled automatically by the security framework.


API	Migration path
WLClient.invokeProcedure(WLProcedureInvocationData invocationData,WLResponseListener responseListener) WL.Client.invokeProcedure(invocationData, options) WLClient.invokeProcedure(WLProcedureInvocationData invocationData, WLResponseListener responseListener, WLRequestOptions requestOptions) WLProcedureInvocationResult	Use the WLResourceRequest instead. Note: The implementation of invokeProcedure uses WLResourceRequest.
WLClient.getEnvironment	Use Cordova plug-ins providing this functionality. Note: For your information, the device.platform plug-in provides this feature.
WLClient.getLanguage	Use Cordova plug-ins providing this functionality. Note: For your information, the cordova-plugin-globalization plug-in provides this feature.
WL.Client.connect(options)	Use WLAuthorizationManager.obtainAccessToken to check connectivity to the server and apply application management rules.