Dual-mode API details

The AppConnect Cordova Plugin provides an enumeration, an event, and methods that allow an app to behave as a dual-mode app.

The ACManagedPolicy enumeration

The ACManagedPolicy enumeration provides the possible managed policy values for the app:

AppConnectCordova.prototype.ACManagedPolicy = {
 
    UNKNOWN:   0, // The AppConnect library has not yet determined
                  // whether the app is managed by Ivanti.
 
    UNMANAGED: 1, // The application is not currently managed by Ivanti.
 
    MANAGED:   2  // The application is currently managed by Ivanti.
 }

The managedPolicy() method

The following method returns the current status of the managed policy for app. The managed policy indicates whether Ivanti is managing the app.

AppConnectCordova.managedPolicy()

Return value: An AppConnectCordova.ACManagedPolicy enumeration value.

Currently, apps have no need to use the managedPolicy() method. Dual-mode apps depend on events to instigate changes to the app’s dual-mode state.

The 'appconnect.managedPolicyChangedTo' event

The AppConnect Cordova Plugin generates the 'appconnect.managedPolicyChangedTo' event to provide managed policy status updates after the plugin initialization is completed.

The event object passed to the event handler contains:

Event object properties	Description
newManagedPolicy	An AppConnectCordova.ACManagedPolicy enumeration value

Event handler for 'appConnect.managedPolicyChangedTo' event

When a change has occurred to the managed policy, the AppConnect Cordova Plugin:

Stores the new ACManagedPolicy value so that subsequent calls to the AppConnectCordova.managedPolicy() method return the updated policy.

Generates the 'appconnect.managedPolicyChangedTo' event.

In a dual-mode app, add an event listener to your document object for the 'appconnect.managedPolicyChangedTo' event. For example:

 document.addEventListener('appconnect.managedPolicyChangedTo',
                            this.onManagedPolicyChangedTo, false);

Your app handles the new managed policy status by changing app’s state to AppConnect Mode or Non-AppConnect Mode as described in:

•API call sequence when the app launches for the first time

•API call sequence when user requests Non-AppConnect Mode

The stop method

The following method shuts down the AppConnect library for the app.

AppConnectCordova.stop()

The app calls the AppConnectCordova.stop() method when it changes state to Non-AppConnect Mode.

If at a later time, the user requests to change to AppConnect Mode, the app restarts the AppConnect library.

For an example of when to call the AppConnectCordova.stop() method, see API call sequence when user requests AppConnect Mode.

For an example of restarting the AppConnect library, see API call sequence when user requests AppConnect Mode.

The retire method

The following method informs the AppConnect library that the app is retiring. Normally, the server decides when to retire an app. In this case, the app is retiring itself.

AppConnectCordova.retire()

Calling retire() causes the AppConnect library to:

•clean up information it keeps about the app, including secure data.

•set its managedPolicy status for the app to UNKNOWN.

IMPORTANT: An app must call AppConnectCordova.retire() and then immediately call AppConnectCordova.stop() when it is changing to Non-AppConnect Mode.

API call sequence when the app launches for the first time

When a dual-mode app launches for the first time, it does not know whether it is managed by Ivanti. It waits for an 'appConnect.managedPolicyChangedTo' event to determine whether to continue in AppConnect Mode or Non-AppConnect Mode.

Therefore, when launching for the first time, the app does the following:

Sets the dual-mode state to Undecided, and persistently stores it.

Starts the AppConnect library after receiving the the Cordova 'deviceready' event:

AppConnectCordova.initialize();

Waits for the 'appConnect.managedPolicyChangedTo' event.

In the event handler for the 'appConnect.managedPolicyChangedTo' event, the app changes its dual-mode state. The state change depends on the value of the newManagedPolicy property in the event object:

If the value is MANAGED, the app changes to AppConnect Mode.

If the value is UNMANAGED, the app changes to Non-AppConnect Mode.

If the app changes to AppConnect Mode, it persistently stores its new dual-mode state. It begins behaving as an AppConnect app. For example, it enforces DLP policies.

If the app changes to Non-AppConnect Mode, it does the following:

Calls AppConnectCordova.retire() and then stops the AppConnect library:

      AppConnectCordova.retire();
      AppConnectCordova.stop();

Persistently stores its new state.

Begins behaving as a regular, non-AppConnect app.

API call sequence when the app subsequently launches

When a dual-mode app subsequently launches, it relies on its persisted dual-mode state to determine whether the behave as an AppConnect app.

When launching for a subsequent time, the app does the following:

Gets its persisted dual-mode state.

Continues as a regular, non-AppConnect app if the dual-mode state is Non-AppConnect Mode.

The app does not call AppConnectCordova.initialize() to start the AppConnect library in this case.

The remaining steps do not apply.

Starts the AppConnect library if the dual-mode state is anything except Non-AppConnect Mode.

   AppConnectCordova.initialize();

Waits for the 'appconnect.isReady' event before accessing other AppConnectCordova JavaScript interfaces such as AppConnectCordova.authState(), AppConnectCordova.authMessage(), and AppConnectCordova.config().

Continues as an AppConnect app if the dual-mode state is AppConnect Mode.

API call sequence when user requests Non-AppConnect Mode

If the device user, through the app’s user interface, requests to change to Non-AppConnect Mode, the app makes the change.

The app does the following:

Performs its usual retire actions, such as removing all its sensitive data, since regular apps do not have sensitive data.

Persistently saves its dual-mode state as Non-AppConnect Mode.

Calls the AppConnectCordova.retire() method, and then stops the AppConnect library.

      AppConnectCordova.retire();
      AppConnectCordova.stop();

Continues as a regular, non-AppConnect app.

When the app next launches, it checks its dual-mode state. Because the state is Non-AppConnect Mode, the app does not start the AppConnect library.

API call sequence when user requests AppConnect Mode

If the device user, through the app’s user interface, requests to change to AppConnect Mode, the app attempts to make the change.

The app does the following:

Changes to the Pending AppConnect Mode state.

Starts the AppConnect library by calling AppConnectCordova.initialize().

Waits for the 'appConnect.managedPolicyChangedTo' event.

In the event handler for the 'appConnect.managedPolicyChangedTo' event:

•If the newManagedPolicy property of the event object has the value UNMANAGED:

The app changes its dual-mode state back to Non-AppConnect Mode. The app persistently stores the state.

The app calls AppConnectCordova.retire(), and then stops the AppConnect library:

      AppConnectCordova.retire();
      AppConnectCordova.stop();

The app notifies the user of the failure to change to AppConnect Mode. It continues behaving as a regular, non-AppConnect app.

•If the newManagedPolicy property in the even object has the value MANAGED:

The app changes its dual-mode state to AppConnect Mode. The app persistently stores the state.

The app checks if the authorization status is retired. If it is, the app performs its usual retire actions, such as removing all its sensitive data.

Finally, the app notifies the user of the successful change to AppConnect Mode. It continues behaving as an AppConnect app.