App-specific configuration API details

The AppConnect Cordova Plugin provides an enumeration, an event, and methods that allow an app to receive app-specific configuration from the Ivanti server. For an overview of this feature, see Configuration specific to the app.

The config() method

The following method returns the current key-value pairs for the app-specific configuration:

AppConnectCordova.config()

Return value: A JavaScript object of key-value pairs. Each key and value is a string corresponding to the key and value configured on the server. For example: 

[
    {"serverURL", "enterpriseServer.finance.com"},
    {"userID", "[email protected]"},
    {"appAdvancedFeaturesEnabled", "true"}
]

If no key-value pairs are configured on the Ivanti server, the return value is an empty object: []

Calling config() when your app launches

When your app launches:

1. Upon receiving the Cordova 'deviceready' event, call the method AppConnectCordova.initialize().
2. Wait for the AppConnectCordova event 'appconnect.isReady' before calling the AppConnectCordova.config() method.
3. In the event handler for the 'appconnect.isReady' event, call the AppConnectCordova.config() method. It returns the key-value pairs, if any, that are configured on the Ivanti server for the app. Apply the configuration according to your application’s requirements and logic.

config() return value after updates to app-specific configuration

On any updates to the app-specific configuration while the app is running, the AppConnect Cordova Plugin generates the 'appconnect.configChangedTo' event. Subsequent calls to the AppConnectCordova.config() return the updated key-value pairs.

The 'appconnect.configChangedTo' event

The AppConnect Cordova Plugin generates the 'appconnect.configChangedTo' event when the app-specific configuration changes after the plugin initialization is completed.

The event object passed to the event handler contains:

Event object properties

Description

newConfig

A JavaScript object of key-value pairs. Each key and value is a string corresponding to the key and value configured on the Ivanti server.

For example: 

[
    {"serverURL", "enterpriseServer.finance.com"},
    {"userID", "[email protected]"},
    {"appAdvancedFeaturesEnabled", "true"}
]

If no key-value pairs are configured on the Ivanti server, the return value is an empty object: []

Event handler for 'appConnect.configChangedTo' event

When a change has occurred to the app-specific configuration on the Ivanti server, the AppConnect Cordova Plugin:

1. Stores the updated JavaScript object of key-value pairs so that subsequent calls to the AppConnectCordova.config() method return the updated key-value pairs.
2. Generates the 'appconnect.configChangedTo' event.

You can optionally add an event listener to your document object for the 'appconnect.configChangedTo' event. For example:

document.addEventListener('appconnect.configChangedTo',
                           this.onConfigChangedTo, false);

Add this event listener only if your app uses app-specific configuration key-value pairs that the Ivanti server administrator configures on the Core Admin Portal.

In the event handler, your app:

•Applies the configuration according to your application’s requirements and logic.

•Calls the AppConnectCordova.configApplied() method.

The configApplied() method

After your event handler processes the information provided in the 'appconnect.configChangedTo' event, it must call this acknowledgment method:

AppConnectCordova.configApplied(policyState, message)

Your app passes the following parameters to this method:

•the AppConnectCordova.ACPolicyState value that represents the success or failure of handling the new configuration.

Pass the value APPLIED if the app successfully handled the new configuration. Otherwise, pass the value ERROR. Pass the value UNSUPPORTED if your app does not support configuration from the Ivanti server. If you do not implement an event handler for the 'appconnect.configChangedTo' event, the AppConnect Cordova Plugin behaves as if you passed it UNSUPPORTED.

•a string explaining the AppConnectCordova.ACPolicyState value.

Typically, you use this string to report the reason the app failed to apply the app-specific configuration updates. The string is reported in the Ivanti server log files.