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


Client API changes in V8.0.0

The following changes in the APIs are relevant to migrating your MobileFirst client application.

The following tables list the discontinued client-side API elements in V8.0.0, deprecated client-side API elements in V8.0.0, and suggested migration paths. For more information about migrating client applications, see Migrating client applications to IBM MobileFirst Platform Foundation V8.0.0.


JavaScript APIs

These JavaScript APIs that affect the user interface are no longer supported in v8.0. They can be replaced with available third-party Cordova plug-ins, or by creating custom Cordova plug-ins.

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.

This set of APIs is no longer supported in V8.0.0.

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.


Android APIs

Table 4. Discontinued Android API elements
API element Migration path
WLConfig WLClient.getConfig() No replacement.

WLDevice WLClient.getWLDevice()

WLClient.transmitEvent(org.json.JSONObject event)

WLClient.setEventTransmissionPolicy(WLEventTransmissionPolicy policy)

WLClient.purgeEventTransmissionBuffer()

Use Android API or third-party packages for GeoLocation.
WL.Client.getUserInfo(realm, key)

WL.Client.updateUserInfo(options)

No replacement.
WL.Client.getUserInfo(realm, key

WL.Client.updateUserInfo(options)

No replacement
WLClient.checkForNotifications() Use WLAuthorizationManager.obtainAccessToken("", listener) to check connectivity to the server and apply application management rules.
WLClient.login(java.lang.String realmName, WLRequestListener listener, WLRequestOptions options)

WLClient.login(java.lang.String realmName, WLRequestListener listener)

Use AuthorizationManager.login()
WLClient.logout(java.lang.String realmName, WLRequestListener listener, WLRequestOptions options)

WLClient.logout(java.lang.String realmName, WLRequestListener listener)

Use AuthorizationManager.logout().
WLClient.obtainAccessToken(java.lang.String scope,WLResponseListener responseListener) Use WLAuthorizationManager.obtainAccessToken(String, WLAccessTokenListener) to check connectivity to the server and apply application management rules.
WLClient.getLastAccessToken()

WLClient.getLastAccessToken(java.lang.String scope)

Use AuthorizationManager.
WLClient.getRequiredAccessTokenScope(int status, java.lang.String header) Use AuthorizationManager.
WLClient.logActivity(java.lang.String activityType) Use com.worklight.common.Logger . For more information, see Logger SDK.
WLAuthorizationPersistencePolicy No replacement. To implement authorization persistence, store the authorization token in the application code and create custom HTTP requests. For more information, see Java™ custom resource-request implementation sample.
WLSimpleSharedData.setSharedToken(myName, myValue)

WLSimpleSharedData.getSharedToken(myName)

WLSimpleSharedData.clearSharedToken(myName)

Use the Android APIs to share tokens across applications.
WLUserCertificateManager.deleteCertificate(android.content.Context context) No replacement
BaseChallengeHandler.submitFailure(WLResponse wlResponse) Use BaseChallengeHandler.cancel().
ChallengeHandler For custom gateway challenges, use GatewayChallengeHandler. For MobileFirst security-check challenges, use SecurityCheckChallengeHandler. For more information about the V8.0.0 challenge-handler APIs, see Client security APIs.
WLChallengeHandler Use SecurityCheckChallengeHandler. For more information about the V8.0.0 challenge-handler APIs, see Client security APIs.
ChallengeHandler.isCustomResponse() Use GatewayChallengeHandler.canHandleResponse().
ChallengeHandler.submitAdapterAuthentication Implement similar logic in your challenge handler. For custom gateway challenge handlers, use GatewayChallengeHandler. For MobileFirst security-check challenge handlers, use SecurityCheckChallengeHandler.

Table 5. Deprecated Android API elements
API Migration path
WLClient.invokeProcedure(WLProcedureInvocationData invocationData, WLResponseListener responseListener)

Deprecated. Use WLResourceRequest

Note: The implementation of invokeProcedure uses WLResourceRequest.

WLClient.connect(WLResponseListener responseListener)

WLClient.connect(WLResponseListener responseListener,WLRequestOptions options)

Use WLAuthorizationManager.obtainAccessToken("", listener) to check connectivity to the server and apply application management rules.

Table 6. Android APIs depending on the legacy org.apach.http APIs are no longer supported
API element Migration path
org.apache.http.Header[] is now deprecated. Therefore, the following methods are removed:  

org.apache.http.Header[] WLResourceRequest.getAllHeaders()

Use instead the new Map<String, List<String>> WLResourceRequest.getAllHeaders() API.

WLResourceRequest.addHeader(org.apache.http.Header header)

Use instead the new WLResourceRequest.addHeader(String name, String value) API.

org.apache.http.Header[] WLResourceRequest.getHeaders(java.lang.String headerName)

Use instead the new List<String> WLResourceRequest.getHeaders(String headerName) API.

org.apache.http.Header WLResourceRequest.getFirstHeader(java.lang.String headerName)

Use instead the new WLResourceRequest.getHeaders(String headerName) API.

WLResourceRequest.setHeaders(org.apache.http.Header[] headers)

Instead, use the new WLResourceRequest.setHeaders(Map<String, List<String>> headerMap) API.

WLResourceRequest.setHeader(org.apache.http.Header header)

Instead, use the new WLResourceRequest.setHeaders(Map<String, List<String>> headerMap) API.
org.apache.http.client.CookieStore WLClient.getCookieStore() Replaced with java.net.CookieStore getCookieStore WLClient.getCookieStore()

java.net.CookieStore getCookieStore WLClient.getCookieStore()

WLClient.setAllowHTTPClientCircularRedirect(boolean isSet) No replacement. MFP Client allows circular redirects.

WLHttpResponseListener WLResourceRequest, all methods that take WLHttpResponseListener:

WLResourceRequest.send(java.util.HashMap formParameters,WLHttpResponseListener listener)

WLResourceRequest.send(org.json.JSONObject json, WLHttpResponseListener listener)

WLResourceRequest.send(byte[] data, WLHttpResponseListener listener)

WLResourceRequest.send(java.lang.String requestBody,WLHttpResponseListener listener)

WLResourceRequest.send(WLHttpResponseListener listener)

WLClient.sendRequest(org.apache.http.client.methods.HttpUriRequest request,WLHttpResponseListener listener)

WLClient.sendRequest(org.apache.http.client.methods.HttpUriRequest request, WLResponseListener listener)

Removed due to deprecated Apache HTTP Client dependencies. Create your own request to have full control over the request and response.

The com.worklight.androidgap.api package provides the Android platform functionality for Cordova apps. In MobileFirst, a number of changes were made to accommodate the Cordova integration.

Table 7. Discontinued Android gap elements (com.worklight.androidgap.api)
API element Migration path
The Android activity was replaced with the Android context.  
static WL.createInstance(android.app.Activity activity) static WL.createInstance(android.content.Context context)

Creates a shared instance.

static WL.getInstance() static WL.getInstance()

Gets an instance of the WL class. This method cannot be called before WL.createInstance(Context).


Objective C API

Table 8. Discontinued iOS Objective C APIs
API element Migration path
[WLClient getWLDevice][WLClient transmitEvent:]

[WLClient setEventTransmissionPolicy]

[WLClient purgeEventTransmissionBuffer]

Geolocation removed. Use native iOS or third-party packages for GeoLocation.
WL.Client.getUserInfo(realm, key)

WL.Client.updateUserInfo(options)

No replacement.
WL.Client.deleteUserPref(key, options) No replacement. We can use an adapter and the MFP.Server.getAuthenticatedUser API to manage user preferences.
[WLClient getRequiredAccessTokenScopeFromStatus] Use WLAuthorizationManager obtainAccessTokenForScope.
[WLClient login:withDelegate:] Use WLAuthorizationManager login.
[WLClient logout:withDelegate:] Use WLAuthorizationManager logout.
[WLClient lastAccessToken]

[WLClient lastAccessTokenForScope:]

Use WLAuthorizationManager obtainAccessTokenForScope.
[WLClient obtainAccessTokenForScope:withDelegate:]

[WLClient getRequiredAccessTokenScopeFromStatus:authenticationHeader:]

Use WLAuthorizationManager obtainAccessTokenForScope.
[WLClient isSubscribedToAdapter:(NSString *) adaptereventSource:(NSString *) eventSource Use Objective-C client-side push API for iOS apps from the IBMMobileFirstPlatformFoundationPush framework. For more information, see Migrating to push notifications from event source-based notifications.
[WLClient - (int) getEventSourceIDFromUserInfo: (NSDictionary *) userInfo] Use Objective-C client-side push API for iOS apps from the IBMMobileFirstPlatformFoundationPush framework. For more information, see Migrating to push notifications from event source-based notifications.
[WLClient invokeProcedure: (WLProcedureInvocationData *) ] Deprecated. Use WLResourceRequest instead.
[WLClient sendUrlRequest:delegate:] Use [WLResourceRequest sendWithDelegate:delegate] instead.
[WLClient (void) logActivity:(NSString *) activityType] Removed. Use an Objective C logger.
[WLSimpleDataSharing setSharedToken: myName value: myValue]

[WLSimpleDataSharing getSharedToken: myName]]

[WLSimpleDataSharing clearSharedToken: myName]

Use the OS APIs to share tokens across applications.
BaseChallengeHandler.submitFailure(WLResponse *)challenge Use BaseChallengeHandler.cancel().
BaseProvisioningChallengeHandler No replacement. Device provisioning is now handled automatically by the security framework.
ChallengeHandler For custom gateway challenges, use GatewayChallengeHandler. For MobileFirst security-check challenges, use SecurityCheckChallengeHandler. For more information about the V8.0.0 challenge-handler APIs, see Client security APIs.
WLChallengeHandler Use SecurityCheckChallengeHandler. For more information about the V8.0.0 challenge-handler APIs, see Client security APIs.
ChallengeHandler.isCustomResponse() Use GatewayChallengeHandler.canHandleResponse().
ChallengeHandler.submitAdapterAuthentication Implement similar logic in your challenge handler. For custom gateway challenge handlers, use GatewayChallengeHandler. For MobileFirst security-check challenge handlers, use SecurityCheckChallengeHandler.


Windows C# API

Table 9. Deprecated Windows C# API elements
Category Description Recommended action
     
C# API Classes ChallengeHandler For custom gateway challenges, use GatewayChallengeHandler. For MobileFirst security-check challenges, use SecurityCheckChallengeHandler. For more information about the V8.0.0 challenge-handler APIs, see Client security APIs.
ChallengeHandler. isCustomResponse() Use GatewayChallengeHandler.canHandleResponse().
ChallengeHandler.submitAdapterAuthentication Implement similar logic in your challenge handler. For custom gateway challenge handlers, use GatewayChallengeHandler. For MobileFirst security-check challenge handlers, use SecurityCheckChallengeHandler.
ChallengeHandler.submitFailure(WLResponse wlResponse) For custom gateway challenge handlers, use GatewayChallengeHandler.Shouldcancel(). For MobileFirst security-check challenge handlers, use SecurityCheckChallengeHandler.ShouldCancel().
WLAuthorizationManager Use WorklightClient.WorklightAuthorizationManager instead.
WLChallengeHandler Use SecurityCheckChallengeHandler. For more information about the V8.0.0 challenge-handler APIs, see Client security APIs.
WLChallengeHandler.submitFailure(WLResponse wlResponse) Use SecurityCheckChallengeHandler.ShouldCancel().
WLClient Use WorklightClient instead.
WLErrorCode Not supported.
WLFailResponse Use WorklightResponse instead.
WLResponse
WLProcedureInvocationData Use WorklightProcedureInvocationData instead.
WLProcedureInvocationFailResponse Not supported.
WLProcedureInvocationResult Not supported.
WLRequestOptions Not supported.
WLResourceRequest Use WorklightResourceRequest instead.
C# API Interfaces WLHttpResponseListener Not supported.
WLResponseListener The response will be available as a WorklightResponse object
WLAuthorizationPersistencePolicy Not supported.

Parent topic: Migrating apps from earlier releases