Class WL.Client 

WL.Client
Description:
This collection of topics lists the public methods of the IBM® MobileFirst® runtime client API for mobile apps, desktop, and web. WL.Client is a JavaScript client library that provides access to IBM MobileFirst capabilities. You can use WL.Client to perform the following types of functions:
  • Initialize and reload the application
  • Manage authenticated sessions
  • Obtain general application information
  • Retrieve and update data from corporate information systems
  • Store and retrieve user preferences across sessions
  • Internationalize application texts
  • Specify environment-specific user interface behavior
  • Store custom log lines for auditing and reporting purposes in special database tables
  • Use functions specific to iPhone, iPad, Android, BlackBerry 6 and 7, and Windows Phone 8 devices
Calls to the MobileFirst Server
WLClient uses asynchronous JavaScript calls, which accept an options parameter. Success and failure handlers receive a response parameter. The API consists of many calls, listed here.
WLClient uses asynchronous JavaScript calls to access the IBM MobileFirst Server. Each asynchronous method accepts an options parameter, which includes success and failure handlers to communicate the results of the call. If you want to be notified when an asynchronous function returns, you must supply these callback functions within the options parameter when you call the function.
Augmented Options
The options parameter often contains additional properties applicable to the specific method that is being called. These additional properties are detailed in the description of the specific method.
Augmented Response
The success and failure handlers of all asynchronous calls always receive a response parameter that contains a common set of properties. Some calls pass additional properties in the response object of the success and failure handlers. In such cases, these additional properties are detailed in the description of the specific method.
Quick Reference
The MobileFirst Client API consists of the following API methods:
  • General application methods
    • Lifecycle: WL.Client.init, WL.Client.reloadApp
    • Connectivity: WL.Client.setHeartBeatInterval, WL.Client.connect, Connectivity-related JavaScript Events
    • Session management methods: WL.Client.getUserName, WL.Client.getLoginName, WL.Client.login, WL.Client.logout, WL.Client.isUserAuthenticated, WL.Client.getUserInfo, WL.Client.updateUserInfo
    • Data access methods: WL.Client.invokeProcedure
    • Activity logging methods: WL.Client.logActivity. Deprecated since V7.0.
    • User preference methods: WL.Client.setUserPref, WL.Client.getUserPref(key)
    • Application properties methods: WL.Client.getEnvironment, WL.Client.getAppProperty
    • Error handling: WL.App.getErrorMessage
    • Debugging: The WL.Logger object

  • Mobile functionality and UI
    • Push notification API: WL.Client.Push.isPushSupported, WL.Client.Push.isPushSMSSupported, WL.Client.Push.onReadyToSubscribe, WL.Client.Push.registerEventSourceCallback, WL.Client.Push.subscribe, WL.Client.Push.subscribeSMS, WL.Client.Push.unsubscribe, WL.Client.Push.unsubscribeSMS, WL.Client.Push.enableBroadcast, WL.Client.Push.disableBroadcast, WL.Client.Push.subscribeToTag, WL.Client.Push.unsubscribeFromTag, WL.Client.Push.isTagSubscribed, WL.Client.Push.registerBroadcastCallback, WL.Client.Push.registerTagCallback
    • Network details: WL.Device.getNetworkInfo
    • Opening a URL: WL.App.openURL
    • Options menu: WL.OptionsMenu
    • Tab bar: Tab Bar API
    • Badge: WL.Badge.setNumber
    • Toast: WL.Toast.show
    • Globalization: WL.App.getDeviceLocale, WL.App.getDeviceLanguage
    • Back button: WL.App.overrideBackButton, WL.App.resetBackButton
    • Dialog box: WL.SimpleDialog
    • Busy indicator: WL.BusyIndicator (constructor)
    • Closing an app: WL.App.close: Deprecated
    • Accessing native pages on mobile apps: WL.NativePage.show
    • Switching between HTML Pages: WL.Fragment.load,Class WL.Page: Both deprecated
    • Encrypted offline cache: WL.EncryptedCache
    • Clipboard: WL.App.copyToClipboard

  • Web and desktop widget methods
    • Desktop window state:, WL.Client.close, WL.Client.minimize
    • Globalization: WL.Client.getLanguage

  • Mechanisms used by the WLClient methods
    • The Options Object, Timeout
Requires:
prototype.js
gadgetCommunicationAPI.js
wlcommon.js
messages.js
worklight.js
Note:
Although JavaScript does not support encapsulation, do not use any method or member not listed in this document. Their semantics or existence is not guaranteed in future versions of the IBM MobileFirst Client API.
Method Summary
Method Attributes Method Name and Description
 
addGlobalHeader(headerName, headerValue)
Adds an HTTP header to be used in server requests issued by an IBM MobileFirst framework.
 
checkForDirectUpdate(options)
Checks whether direct update is available.
 
clearSharedToken(object)
Clears a previously saved value associated with key from applications participating in simple shared data who are in the same application family, defined by the same family name and same application signing key.
 
close()
Closes a widget on Adobe AIR.
 
connect(options)
Establishes a connection to the MobileFirst Server.
 
createChallengeHandler(realmName)
Creates a challenge handler object.A realm name must be supplied as a parameter.
 
createProvisioningChallengeHandler(realmName)
Creates a new challenge handler instance responsible for a specified realm.
 
createWLChallengeHandler(realmName)
Creates a challenge handler object to handle challenges that are sent by the MobileFirst Server.
 
deleteCookie(name)
Deletes a cookie from the native HTTP client cookie storage.
 
deleteUserPref(key, options)
Delete a user preference key.
 
getAppProperty(property)
Returns the value of the specified property.
 
getCookies()
Retrieves cookies from the native HTTP client.
 
getEnvironment()
Identifies the type of environment in which the application is running.
 
getLanguage()
Return the language code of the language being used.
 
getLastAccessToken(scope)
Gets the last obtained access token for a given scope, or the last access token for any scope, of none is provided.
 
getLoginName(realm)
Returns the login name of the user who is currently logged in.
 
getRequiredAccessTokenScope(status, header)
Determines whether an access token is requested by the server, and returns the required scope.
 
getSharedToken(object)
Retrieves a previously saved value associated with key from application participating in simple shared data who are in the same application family, defined by the same family name and same application signing key.
 
getUserInfo(realm, key)
Returns a user property.
 
getUserName(realm)
Returns the user name of the user who is currently logged in.
 
getUserPref(key)
Returns the local value of a specified user preference.
 
hasUserPref(key)
Checks whether a user preference is defined locally in the application.
 
init(options)
Initializes the WL.Client object.
 
invokeProcedure(invocationData, options)
Invokes a procedure that is exposed by an IBM MobileFirst adapter.
 
isConnected()
This method is deprecated.
 
isUserAuthenticated(realm)
Checks whether the user is authenticated.
 
logActivity(activityType)
Reports user activity.
 
login(realm, options)
Logs in to a specific realm.
 
logout(realm, options)
Logs out to a specific realm.
 
minimize()
Minimizes a widget in Adobe Air.
 
obtainAccessToken(scope, onSuccess, onFailure)
Obtains an OAuth 2.0 access token from the MobileFirst server.
 
pinTrustedCertificatePublicKey(certificateFilename)
Pins the host X509 certificate public key to the client application.
 
purgeEventTransmissionBuffer()
Purges the internal event transmission buffer.
 
reloadApp()
Reloads the application It can be used to recover an application from errors.
 
removeGlobalHeader(headerName)
Removes the global HTTP header added by the WL.Client.addGlobalHeader API call
 
setCookie(cookie)
Adds a cookie to the native HTTP client.
 
setEventTransmissionPolicy(policy)
Configures the transmission of events from the client to the server, according to the provided transmission policy.
 
setHeartBeatInterval(interval)
Sets the interval of the heartbeat signal.
 
setSharedToken(object)
Saves a key/value pair such that it is available to other applications participating in simple shared data who are in the same application family, defined by the same family name and same application signing key.
 
setUserPref(key, value, options)
Creates a user preference, or updates the value of an existing user preference.
 
setUserPrefs(userPrefsHash, options)
Creates or updates one or more user preferences.
 
transmitEvent(event, immediate)
Transmits a provided event object to the server.
 
updateUserInfo(options)
Refreshes user data after an exception.
Method Detail
addGlobalHeader
addGlobalHeader(headerName, headerValue)
Adds an HTTP header to be used in server requests issued by an IBM MobileFirst framework. The HTTP header is used in all requests until removed by the WL.Client.removeGlobalHeader API call.
Parameters:
headerName - Mandatory. The name of the header to be added.
headerValue - Mandatory. The value of the header to be added.
Example:
WL.Client.addGlobalHeader("MyCustomHeader","abcdefgh");
checkForDirectUpdate
checkForDirectUpdate(options)
Checks whether direct update is available. An asynchronous function that checks if direct update is available. If direct update is available, then a challenge handler is triggered. If an onSuccess callback is received, then there is no direct update available on the server.
Parameters:
options - Optional. A standard options object.
clearSharedToken
clearSharedToken(object)
Clears a previously saved value associated with key from applications participating in simple shared data who are in the same application family, defined by the same family name and same application signing key. This API call is only applicable in Android and IOS environments. It is a safe, but no-op, call in other environments.
Parameters:
object - Object containing the key to clear, like {key: 'myKey'}
Returns:
Promise
close
close()
Closes a widget on Adobe AIR.
Note:
This method is only applicable to widgets that are running on Adobe AIR.
Closes the AIR widget (making it exit).
connect
connect(options)
Establishes a connection to the MobileFirst Server.

The connect() method tries to establish a connection to the MobileFirst Server. You must call this method before calling any other WL.Client method that communicates with the MobileFirst Server.

Parameters:
options - Optional. A JSON block with the following additional properties:

onSuccess

A callback function invoked when the connection to the MobileFirst Server is established.

onFaiure

A Callback function invoked when the WL.Client.connect method fails to establish connection with the MobileFirst server. The callback receives one parameter of type WL.FailResponse, which might be null if connect is called while a previous call to connect has not yet returned.

timeout

Number of milliseconds to wait for the server response before failing with a request timeout.
Note:
Connectivity-related JavaScript Events
The IBM MobileFirst runtime framework fires two events, to which you can listen to capture changes in connectivity. The events are fired only on change of connectivity state.
  • WL.Events.WORKLIGHT_IS_CONNECTED: fired when the application connects to the Worklight Server.
  • WL.Events.WORKLIGHT_IS_DISCONNECTED: fired when loss of connectivity to MobileFirst Server is detected.

document.addEventListener(WL.Events.WORKLIGHT_IS_CONNECTED , handleConnectionUp, false);
document.addEventListener(WL.Events.WORKLIGHT_IS_DISCONNECTED, handleConnectionDown, false);
createChallengeHandler
createChallengeHandler(realmName)
Creates a challenge handler object.A realm name must be supplied as a parameter.
Parameters:
realmName - The realm name representing the challange, in configuration file (authenticationConfig.xml)
createProvisioningChallengeHandler
createProvisioningChallengeHandler(realmName)
Creates a new challenge handler instance responsible for a specified realm. In order for it to function developer must implement the following mandatory methods, as described in the MobileFirst Knowledge Center.
  • isCustomResponse()
  • handleChallenge()
Parameters:
realmName - Realm name representing the challange, in configuration file (authenticationConfig.xml). Realm name. Must be supplied as a parameter.
Note:
This method is for Device Provisioning only.
createWLChallengeHandler
createWLChallengeHandler(realmName)
Creates a challenge handler object to handle challenges that are sent by the MobileFirst Server. A WLChallengeHandler works only with an authentication realm that is based on the MobileFirst authentication protocol, that is, for which the server side authenticator instance extends one of the MobileFirst provided authenticators, such as WorklightProtocolAuthenticator or UsernamePasswordAuthenticator, or directly implements the WorklightAuthenticator interface.   There must be only one challenge handler per realm. To comply with the MobileFirst authentication protocol, the challenge that the challenge handler receives must be a JSON object.

When you create a WLChallengeHandler, you must implement the following methods:

  • handleChallenge() - This method is called when the MobileFirst Server returns a challenge for the realm.
  • processSuccess() - This method is called when the MobileFirst Server reports an authentication success.
  • handleFailure() - This method is called when the MobileFirst Server reports an authentication failure.
Parameters:
realmName - Realm name that represents the challenge, in the authenticationConfig.xml configuration file. Use this name to identify the realm that requires authentication.  Used to identify which realm requires authentication.
deleteCookie
deleteCookie(name)
Deletes a cookie from the native HTTP client cookie storage. This function is asynchronous and returns a promise.
Parameters:
name - Mandatory. Cookie name.
Returns:
Promise
Example:
WL.Client.deleteCookie(myCookie).then(successFlow);
deleteUserPref
deleteUserPref(key, options)
Delete a user preference key. An asynchronous function that deletes a specified user preference key.
Parameters:
key - Mandatory. The user preference key. Can be up to 128 characters long.
options - Optional. A standard options object.
Note:
The local user preferences in the application are updated only when a successful response is received from the server.
getAppProperty
getAppProperty(property)
Returns the value of the specified property.
Parameters:
property - Mandatory. One of the following values:
  • WL.AppProperty.AIR_ICON_16x16_PATH
    For AIR widgets only; the relative path to the AIR icon.
  • WL.AppProperty.AIR_ICON_128x128_PATH
    For AIR widgets only; the relative path to the AIR icon.
  • WL.AppProperty.DOWNLOAD_APP_LINK
    For desktop widgets only; the URL for downloading an updated version of the application.
  • WL.AppProperty.APP_DISPLAY_NAME
    The application display name, as defined in the application descriptor.
  • WL.AppProperty.APP_LOGIN_TYPE
    The application login type, as defined in the application descriptor: never, onstartup, or ondemand
  • WL.AppProperty.APP_VERSION
    The application version, as defined in the application descriptor (a newer version might be available on the MobileFirst Server)
  • WL.AppProperty.LATEST_VERSION
    For Desktop application only: The latest application version available on the MobileFirst Server.
  • WL.AppProperty.MAIN_FILE_PATH
    For web environments only; the absolute URL to the main application file.
  • WL.AppProperty.SHOW_IN_TASKBAR
    For AIR widgets only; a Boolean stating whether the Air application shows in the taskbar, as defined in the descriptor.
  • WL.AppProperty.THUMBNAIL_IMAGE_URL
    An absolute URL for the thumbnail image for the application.
Note:
For Cordova apps, only the APP_VERSION property is supported.
getCookies
getCookies()
Retrieves cookies from the native HTTP client. This function is asynchronous and returns a promise. The array of cookies will be passed as a parameter to resolve callback.
Returns:
Promise
Example:
WL.Client.getCookies().then(function(cookies){...})
Note:
HttpOnly and Secure cookies are not returned.
getEnvironment
getEnvironment()
Identifies the type of environment in which the application is running. Such as iPhone, Android, or Windows.
Returns:
A constant that identifies the type of environment. The valid values are defined in the WL.Environment variable in the worklight.js file, and are as follows:
  • WL.Environment.ADOBE_AIR
  • WL.Environment.ANDROID
  • WL.Environment.IPAD
  • WL.Environment.IPHONE
  • WL.Environment.MOBILE_WEB
  • WL.Environment.PREVIEW (when the application runs in Preview mode)
  • WL.Environment.WINDOWS_PHONE_8
  • WL.Environment.WINDOWS8
  • WL.Environment.DESKTOPBROWSER
  • WL.Environment.BLACKBERRY
  • WL.Environment.BLACKBERRY10

When an app is running in Preview mode, this method returns WL.Environment.PREVIEW, regardless of the previewed environment. There are two reasons for this behavior:
  • Environment - specific code can fail when invoked from the browser (because the environment might support features that are not available in the browser).
  • WL.Client behaves differently in different environments (for example, cookie management).

A good practice is to rely on the IBM MobileFirst UI optimization framework and separate environment-dependent JS to separate files rather than using the WL.Client.getEnvironment() function. For Cordova apps, use the standard Cordova API cordova.platformId.
getLanguage
getLanguage()
Return the language code of the language being used. This method returns the language or dialect code of the language currently being used for the application.
Returns:
The language or dialect code of the currently set language, or NULL if no language is set. The language or dialect code has the format ll or ll-cc, where ll is a two-letter ISO 639-1 language code and cc is a two-letter ISO 3166-1-alpha-2 country or region code.
Note:
This method is not relevant for mobile operating systems. Use mobile locale methods instead.
getLastAccessToken
getLastAccessToken(scope)
Gets the last obtained access token for a given scope, or the last access token for any scope, of none is provided.
Parameters:
scope - Optional. The scope of the requested token, if the scope is null, the last obtained access token will be returned.
Returns:
The token, or null if no token was previously obtained for the requested scope.
Deprecated:
Since version 7.0
getLoginName
getLoginName(realm)
Returns the login name of the user who is currently logged in.
Parameters:
realm - Optional. The name of a realm that is defined in the authenticationConfig.xml file.
If no value is specified, the method returns the login name in the resource realm that is assigned to the application when it was deployed.
Returns:
The login name of the user who is logged in, or NULL if the login name is unknown.
Note:
This method is applicable only to applications that support login.
This method returns the login name of the user who is logged in. The login name is the name that the user entered when logging in.
getRequiredAccessTokenScope
getRequiredAccessTokenScope(status, header)
Determines whether an access token is requested by the server, and returns the required scope.
Parameters:
status - The status code of the response.
header - The value of the WWW-Authenticate header of the response.
Returns:
The scope requested by the server, or null if the response is not related to MobileFirst access tokens.
Deprecated:
Since version 7.0
getSharedToken
getSharedToken(object)
Retrieves a previously saved value associated with key from application participating in simple shared data who are in the same application family, defined by the same family name and same application signing key.

This API call is only applicable in Android and IOS environments. It is a safe, but no-op, call in other environments.

Parameters:
object - Object containing the key to retrieve, like {key: 'myKey'}
Returns:
Promise containing the retrieved value, or null if no value is found
getUserInfo
getUserInfo(realm, key)
Returns a user property. This method returns a user property with the specified key in the specified authentication realm.
Parameters:
realm - Mandatory. The name of a realm that is defined in the authenticationConfig.xml file.
key - Mandatory. The name of the key that is present in the specified realm.
getUserName
getUserName(realm)
Returns the user name of the user who is currently logged in.

This method returns the user name of the user who is currently logged in, as defined by the login module used to authenticate the user.

Parameters:
realm - The name of a realm defined in the authenticationConfig.xml file.
If no value is specified, the method returns the user name in the resource realm assigned to the application when it was deployed.
Returns:
The user name of the user who is currently logged in, or NULL if the user name is unknown.
Note:
This method is only applicable to applications that support login.
getUserPref
getUserPref(key)
Returns the local value of a specified user preference.
Parameters:
key - Mandatory. The user preference key.
Returns:
The value of the user preference or NULL if there is no user preference with the specified key. Note that user preferences become available only on connection with the server.
Throws:
An exception is thrown when invalid parameters are passed to the function.
hasUserPref
hasUserPref(key)
Checks whether a user preference is defined locally in the application.
Parameters:
key - Mandatory. The user preference key.
Returns:
Returns true if the preference exists, false otherwise.
Throws:
An exception is thrown when invalid parameters are passed to the function.
init
init(options)
Initializes the WL.Client object. The options of this method reside in the initOptions.js file.
Parameters:
options - An optional options object augmented with the following additional optional properties:
Property Description
Timeout

An integer value, denoting the timeout in milliseconds. The timeout affects all calls from the app to the MobileFirst Server. If not specified, a timeout of 30,000 milliseconds (30 seconds) is used.
enableLogger The use of enableLogger flag is deprecated since V6.2. Use WL.Logger.config function with an object specifying the level instead.
messages

A dictionary object for localizing texts, located in the messages.js file. If not specified, the default object Messages (in the same file) is used.
authenticator

An object that implements the Authenticator API. If not specified, Authenticator is used.
heartBeatIntervalInSecs

An integer value, denoting the interval in seconds between heartbeat messages automatically sent by WLClient to the MobileFirst Server. The default value is 420 (7 minutes).
connectOnStartup

Deprecated: The connectOnStartup init option is deprecated. MobileFirst applications by default are configured to not connect to the MobileFirst Server. If you would like your application to connect to the MobileFirst Server, use WL.Client.connect().

onConnectionFailure

A failure-handling function invoked when connection to the MobileFirst Server, performed on initialization by default, or if the connectOnStartup flag is true, fails.

onUnsupportedVersion

A failure-handling function invoked when the current version of the application is no longer supported (a newer application has been deployed to the server). For more information about the signature of failure-handling functions, see The Options Object.
onRequestTimeout

A failure-handling function invoked when the init() request times out. For more information about the signature of failure-handling functions, see The Options Object.
onUnsupportedBrowser

A failure-handling function invoked when the application is running in an unsupported browser. For more information about the signature of failure-handling functions, see The Options Object.
onDisabledCookies

A failure-handling function invoked when cookies are displayed in the user's browser. For more information about the signature of failure-handling functions, see The Options Object.
onUserInstanceAccessViolation

A failure-handling function invoked when the user is trying to access an application that was provisioned to a different user. For more information about the signature of failure-handling functions, see The Options Object.
onErrorRemoteDisableDenial

A failure-handling function invoked when the server denies access to the application, according to rules defined in the IBM MobileFirst Console. If this function is not provided, the application opens a dialog box, which displays an error message defined in the IBM MobileFirst Console. When used, the function can provide an application-specific dialog box, or can be used to implement additional behavior in situations where the server denies access to the application. It is important to ensure that the application remains offline (not connected).

Parameters:
message: This parameter contains the notification text that you defined in the MobileFirst Console, which indicates that an application is denied access to the MobileFirst Server.
downloadLink: This parameter contains the URL that you defined in the MobileFirst Console to download the new version of the application, that users can find in the appropriate application store.

Example 

var wlInitOptions = {
	connectOnStartup : true,
	onErrorRemoteDisableDenial : function (message, downloadLink) {
	WL.SimpleDialog.show(
		"Application Disabled",
		message,
		[{text: "Close application", handler: function() {WL.App.close();}},
		{text: "Download new version", handler: function() {WL.App.openURL(downloadLink, "_blank");}}]
		);
	}
};

onErrorAppVersionAccessDenial

A failure-handling function invoked when the server denies access to the application, according to rules defined in the IBM MobileFirst Console. If this function is used, the developer takes full ownership of the implementation and handling if Remote Disable took place. If the failure-handling function is not provided, the application opens a dialog box, which displays an error message defined in the IBM MobileFirst Console.
Note: onErrorAppVersionAccessDenial is deprecated since V5.0.6. Instead, use onErrorRemoteDisableDenial.

validateArguments

A Boolean value, indicating whether the IBM MobileFirst Client runtime library validates the number and type of method parameters. The default is true.
updateSilently

This property is no longer available. To create a UI-less Direct Update experience, see "Scenario: Running UI-less direct update" in the topic "Customizing the direct update interface" of the Knowledge Center.
autoHideSplash

A Boolean value, indicating whether the IBM MobileFirst splash-screen will be auto-hidden. To disable automatic hiding of the splash screen set this property to false. Default is true.
onGetCustomDeviceProvisioningProperties

A callback function invoked during the provisioning process of the device ID created by the app on the device. Typical implementation collects an out-of-band provisioning token from the user.
The function receives a function argument resumeDeviceProvisioningProcess, which must be called to resume the provisioning process, and transfers the custom provisioning data as a JSON hash map.

Example: 
In initOptions.js:
var wlInitOptions = {
	...
	...
	onGetCustomDeviceProvisioningProperties: collectCustomProvisioningProperties,
	...
}

In application JavaScript file:
function collectCustomProvisioningProperties (
	resumeDeviceProvisioningProcess) { 
		// Collect provisioning token from user resumeDeviceProvisioningProcess(
		{
			token: token
		}
	);
}
Note:
The onSuccess function is used to initialize the application.
If an onFailure function is not passed, a default onFailure function is called. If onFailure is passed, it overrides any specific failure-handling function.
invokeProcedure
{Promise} invokeProcedure(invocationData, options)
Invokes a procedure that is exposed by an IBM MobileFirst adapter. Prior to invoking a procedure, a connect request to the MobileFirst Server is first initiated.
Parameters:
invocationData - Mandatory. A JSON block of parameters. For a description of the structure of the parameter block.
The WL.Client invokeProcedure function accepts the following JSON block of parameters: 
{
	adapter : 'adapter-name',
	procedure : 'procedure-name',
	parameters : [],
	compressResponse : true/false
}
Property Description
adapter

Mandatory. A string that contains the name of the adapter as specified when the adapter was defined.
procedure

Mandatory. A string that contains the name of the procedure as specified when the adapter was defined.
parameters

Optional. An array of parameters that is passed to the back-end procedure.
compressResponse

Optional. A string that requests the response from the server to be sent in a compressed format to reduce the amount of data that is transferred between MobileFirst Server and the device. The default value, if compressResponse is not specified, is false.
Note:
This option is applicable for Android, iOS, Windows Phone Silverlight 8, Windows 8 universal, BlackBerry 10, Mobile Web, and Adobe AIR. For Mobile Web applications, compression is supported only when the device browser can decompress GZIP data.
If the size of the payload is larger than the compress.response.threshold property set on the server, this option is ignored.

options - Optional. A standard options object, augmented with the following property:
  • The success handler response object can contain the following properties:
    Property Description
    invocationContext

    The invocationContext object that was originally passed to the MobileFirst Server in the callback object.
    invocationResult

    An object that contains the data that is returned by the invoked procedure, and the invocation status. Its format is as follows:

    invocationResult = {
	isSuccessful: Boolean,
	errors : "Error Message"
	// Procedure results go here
}
    Where:
    • isSuccessful – Contains true if the procedure invocation succeeded, false otherwise. If the invocation failed, the failure handler for the request is called.
    • errors – An optional array of strings containing error messages.
    parameters

    Optional. An array of parameters that is passed to the back-end procedure.
  • timeout: Integer. Number of milliseconds to wait for the server response before failing with a request timeout. The default timeout value is 30000 milliseconds (30 seconds).
    • The maximum timeout value in any Windows Phone environment is 60000 milliseconds (60 seconds).
  • The failure handler of this call is called in two cases:
    • The procedure was called but failed. In this case, the invocationResult property is added to the response received by the failure handler. This property has the same structure as the invocationResult property returned to the success handler, but the value of the isSuccessful attribute is false. For the structure of the invocationResult property, see invocationResult.
    • A technical failure resulted in the procedure not being called. In this case, the failure handler receives a standard response object.
Returns:
{Promise} Resolved when the operation is successful. Rejected when there is a failure.
isConnected
isConnected()
This method is deprecated.
Deprecated:
This method is deprecated.
Note:
This method is deprecated since IBM Worklight V4.1.3. Use WL.Device.getNetworkInfo instead.
Returns true if the last request to the WL server was successful.
isUserAuthenticated
isUserAuthenticated(realm)
Checks whether the user is authenticated. Checks whether the user is authenticated in a specified resource realm, or in the resource realm that was assigned to the application when it was deployed.
Parameters:
realm - Optional. The name of a realm name defined in the authenticationConfig.xml file.
If no value is specified, the method uses the resource realm assigned to the application when it was deployed.
Returns:
  • true if the user is authenticated in the realm.
  • false otherwise.
logActivity
logActivity(activityType)
Reports user activity.

This method is used to report user activity for auditing or reporting purposes.
The IBM MobileFirst Server maintains a separate database table to store application statistics.

Parameters:
activityType - Mandatory. A string that identifies the activity.
Deprecated:
The method is deprecated in V7.0. Use WL.Logger instead.
Note:
To ensure that the activity is stored in the database, set reports.exportRawData to true in the worklight.properties file.
login
login(realm, options)
Logs in to a specific realm. An asynchronous function. Logs in to a specific realm.
Parameters:
realm - Mandatory. A realm that defines how the login process is performed. The realm is the one defined in the application descriptor.
options - Optional. A standard options object.
logout
logout(realm, options)
Logs out to a specific realm. An asynchronous function that logs out of a specified realm.
Parameters:
realm - Optional. The realm to be logged out of.
Specify NULL to log out of the resource realm assigned to the application when it was deployed.
options - Optional. A standard options object.
minimize
minimize()
Minimizes a widget in Adobe Air. This method minimizes the AIR widget to the taskbar, or to the tray, as defined in the application descriptor.
Note:
This method is only applicable to widgets that are running on Adobe AIR.
obtainAccessToken
obtainAccessToken(scope, onSuccess, onFailure)
Obtains an OAuth 2.0 access token from the MobileFirst server. The token is required in order to send a request to an external server which uses this MobileFirst authentication method.
Parameters:
scope - Optional. The name of the security test protecting the external resource. If the scope is null, a token for the application's default security test will be obtained.
onSuccess - The success callback. Note that there is no need to parse the response. Instead, use WL.Client.getLastAccessToken(scope) in order to get the last obtained token.
onFailure - The failure callback.
Deprecated:
Since version 7.0
pinTrustedCertificatePublicKey
{Promise} pinTrustedCertificatePublicKey(certificateFilename)
Pins the host X509 certificate public key to the client application. Secured calls to the pinned remote host will be checked for a public key match. Secured calls to other hosts containing other certificates will be rejected. Some mobile operating systems might cache the certificate validation check results. Your app must call the certificate pinning method before making a secured request. Calling this method a second time overrides any previous pinning operation.
Parameters:
certificateFilename - - the name of the certificate file that is located under the certificate folder located in the application root
Returns:
{Promise} Resolved when the operation is successful and the certificate is pinned. Rejected if certificateFilename is undefined, not found or is not in DER format.
purgeEventTransmissionBuffer
purgeEventTransmissionBuffer()
Purges the internal event transmission buffer.

The internal event transmission buffer is purged, and all events awaiting transmission are permanently lost.

reloadApp
reloadApp()
Reloads the application It can be used to recover an application from errors. It is preferable to avoid using it and to use alternative error handling mechanisms instead. The method is mainly available for compatibility with earlier versions.
Note:
Not supported for Cordova apps.
removeGlobalHeader
removeGlobalHeader(headerName)
Removes the global HTTP header added by the WL.Client.addGlobalHeader API call
Parameters:
headerName - Mandatory. The name of the header to be removed.
Example:
WL.Client.removeGlobalHeader("MyCustomHeader");
setCookie
setCookie(cookie)
Adds a cookie to the native HTTP client. This function is asynchronous and returns a promise.
Parameters:
cookie - Mandatory. JSON object with required cookie properties: name, value, domain, path, expires
Returns:
Promise
Example:
WL.Client.setCookie(myCookie).then(successFlow);
setEventTransmissionPolicy
setEventTransmissionPolicy(policy)
Configures the transmission of events from the client to the server, according to the provided transmission policy.
Parameters:
{object} policy - The policy object.
{boolean} policy.eventStorageEnabled Optional - A Boolean value that determines where events are stored. If the value is true, events may be stored in HTML5 session storage. If the value is false, events that are waiting for transmission are stored in memory. The default value is false.
The value true should be used only if the developer of the policy is not concerned about privacy issues involved in storing the events, which include the user's device context.
{number} policy.interval Optional - The transmission interval, in milliseconds. The default value is 60000 (one minute). Before events are transmitted, they are accumulated in storage.
setHeartBeatInterval
setHeartBeatInterval(interval)
Sets the interval of the heartbeat signal. Sets the interval of the heartbeat signal sent to the MobileFirst Server to the specified number of seconds. The heartbeat is used to ensure that the session with the server is kept alive when the app does not issue any call to the server (such as invokeProcedure).
Parameters:
interval - Mandatory. An integer value, denoting the interval in seconds between heartbeat messages automatically sent by WLClient to the MobileFirst Server.
An interval value of -1 disables the heartbeat:
WL.Client.setHeartBeatInterval(-1)
setSharedToken
setSharedToken(object)
Saves a key/value pair such that it is available to other applications participating in simple shared data who are in the same application family, defined by the same family name and same application signing key.

This API call is only applicable in Android and IOS environments. It is a safe, but no-op, call in other environments.

Parameters:
object - Object containing the key/value pair to share, like {key: 'myKey', value: 'myValue'}
Returns:
Promise
setUserPref
setUserPref(key, value, options)
Creates a user preference, or updates the value of an existing user preference. An asynchronous function that creates a user preference, or updates the value of an existing user preference, as follows:
  • If a user preference with the specified user key is already defined, the user preference value is updated.
  • If there is no user preference defined with the specified key, a new user preference is created with the specified key and value. However, if there are already 100 preferences, no preference is created, and the failure handler of the method is called.
Parameters:
key - Mandatory. The user preference key. Can be up to 128 characters long.
value - Mandatory. The value of the user preference. Can be up to 3072 characters long.
options - Optional. A standard options object.
Note:
The local user preferences in the application are updated only when a successful response is received from the server.
setUserPrefs
setUserPrefs(userPrefsHash, options)
Creates or updates one or more user preferences. An asynchronous function that creates one or more new user preferences, updates the values of one or more existing user preferences, or both. For each user preference key and value pair provided, the following action occurs:
  • If a user preference with the specified user key is already defined, the user preference value is updated.
  • If there is no user preference defined with the specified key, a new user preference is created with the specified key and value.
If adding the new user preferences would result in the number of user preferences exceeding 100, then no user preferences are added or updated, and the failure handler of the method is called.
Parameters:
userPrefsHash - Mandatory. A hash object that contains user preference key and value pairs. The key can be up to 128 characters long. The value can be up to 3072 characters long.
options - Optional. A standard options object.
Note:
The local user preferences in the application are updated only when a successful response is received from the server.
transmitEvent
transmitEvent(event, immediate)
Transmits a provided event object to the server.

An event object is added to the transmission buffer. The event object is either transmitted immediately, if the immediate parameter is set to true, otherwise it is transmitted according to the transmission policy. For more information, see WL.Client.setEventTransmissionPolicy. One of the properties for the event object might be the device context, which comprises geo-location and WiFi data. If no device context is transmitted as part of the event, the current device context, as returned by WL.Device.getContext, is added automatically to the event during the transmission process.

Parameters:
{object} event - The event object that is being transmitted. The event object is either a literal object, or a reference to an object.
{boolean} immediate Optional - A Boolean flag that indicates whether the transmission should be immediate (true), or should be based on the transmission policy's interval (false). If immediate is true, previously buffered events are transmitted, as well as the current event. The default value is false.
updateUserInfo
updateUserInfo(options)
Refreshes user data after an exception. Use this method when the application receives an exception after calling the invokeProcedure() method. The method refreshes the data for the following methods:
  • WL.Client.getUserName(realm)
  • WL.Client.getLoginName(realm)
  • WL.Client.isUserAuthenticated(realm)
After such an exception, you can verify the user authentication status by calling this function first, and then the isUserAuthenticated() method.
Parameters:
options - Optional. A standard options object.
© Copyright IBM Corp. 2011, 2015.