Dual-mode API details

The AppConnect for iOS API provides properties 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

typedef enum {
    ACMANAGEDPOLICY_UNKNOWN   =  0, // The AppConnect library has not yet determined
                                    // whether the app is managed by Ivanti.
    ACMANAGEDPOLICY_UNMANAGED =  1, // The application is not currently managed by 		
                                    // Ivanti.
    ACMANAGEDPOLICY_MANAGED   =  2, // The application is currently managed by 
                                    // Ivanti.
 } ACManagedPolicy;

The managedPolicy property

The read-only managedPolicy property on the AppConnect singleton contains an ACManagedPolicy value. The value reflects the current status of the managed policy for the app. The managed policy indicates whether Ivanti is managing the app.

The app can access the managedPolicy property only after:

It has called the -startWithLaunchOptions: method on the AppConnect singleton.
It has received the -appConnectIsReady: callback, that sets the ready property on the AppConnect singleton to YES.

Currently, apps have no need to use the managedPolicy property. Dual-mode apps depend on notifications to instigate changes to the app’s dual-mode state.

After your app starts the AppConnect library, the AppConnect library determines the managed policy value, and then:

updates the managedPolicy property.
calls the -appConnect:managedPolicyChangedTo: method to provide your app the current managed policy value.

Dual mode methods

A dual-mode app uses the following methods:

The +shouldStartAppConnect: class method
The -appConnect:managedPolicyChangedTo: callback method
The stop method
The retire method

The +shouldStartAppConnect: class method

+(BOOL)shouldStartAppConnect;

Dual mode apps call this method to determine whether to start the AppConnect library. The method returns YES if:

the Ivanti client app is installed or
the Ivanti client app had been installed but is now deleted, and the app had previously run in AppConnect Mode

This method is necessary because users often launch an app before the Ivanti client app is installed. When an app launches the first time, the app determines whether it is managed by Ivanti, and therefore determines whether to run as an AppConnect app (AppConnect Mode) or a regular app (Non-AppConnect Mode). Once an app has chosen one of these modes, it cannot change to the other mode without user actions, such as using an app-provided user interface, or re-installing the app. Therefore, an app should call +shouldStartAppConnect: to determine whether to delay choosing between AppConnect Mode and Non-AppConnect Mode until its next launch. If +shouldStartAppConnect: returns NO, the app delays the choice and runs as a regular app. On the app's next launch, if +shouldStartAppConnect: returns YES, it makes the choice to run as an AppConnect app without any user action.

The -appConnect:managedPolicyChangedTo: callback method

You optionally implement this method, which is in the AppConnectDelegate protocol:

-(void) appConnect:(AppConnect *)appConnect managedPolicyChangedTo:
                                 (ACManagedPolicy)newManagedPolicy;

Implement this method only if your app is a dual-mode app.

When a change occurs to the managed policy, the AppConnect library:

Sets the managedPolicy property on the AppConnect object to the new ACManagedPolicy value.
Calls the appConnect:managedPolicyChangedTo: method, which provides the new ACManagedPolicy value in its parameter.

In this method, the app changes its dual-mode state to AppConnect Mode or Non-AppConnect Mode.

The stop method

-(void)stop;

The -stop method on the AppConnect singleton object:

shuts down the AppConnect library for the app.
deallocates the AppConnect shared instance -- the sharedInstance static property on the AppConnect class.

The app calls the -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.

The app can call the +logAtLevel:format: and +logAtLevel:format:args: class methods and get the +(ACLogLevel)logLevel property even after calling -stop:. When the AppConnect library is stopped, the log level is always ACLOGLEVEL_STATUS.

See API call sequence when user requests AppConnect Mode for examples of:

when to call the -stop method
restarting the AppConnect library

The retire method

-(void)retire;

The -retire method on the AppConnect singleton object informs the AppConnect library that the app is retiring. Normally, the Ivanti server decides when to retire an app. In this case, the app is retiring itself.

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 ACMANAGEDPOLICY_UNKNOWN.

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

For an example of when to call the -retire method, see API call sequence when user requests AppConnect Mode.

API call sequence when the app launches

When a dual-mode app launches, it uses its dual-mode state and whether AppConnect is available to determine how to proceed. It must determine whether it is managed by Ivanti, and therefore whether to behave as an AppConnect app or a regular app.

Dual-mode sample app code snippets illustrating this behavior are from:

File: Policies.m
Methods: -initPrivateWithLaunchOptions: and -appConnect:managedPolicyChangedTo:

Specifically, when launching, the app does the following:

Gets its persisted dual-mode state and data encryption state. On the first launch, because no persisted states exist, the app sets the dual-mode state to Undecided and the encryption state to Unencrypted.

Determines whether to start the AppConnect library.

    // Do not start the AppConnect library when the dual-mode state is Non-AppConnect Mode.
    // Otherwise, start it only if shouldStartAppConnect() says you should.
    if (DMS_NonACMode != _state && [AppConnect shouldStartAppConnect]) {
 
        [AppConnect initWithDelegate:self];
        _ac = [AppConnect sharedInstance];
        [_ac startWithLaunchOptions:launchOptions];
 
     }
    else if (DMS_Undecided == _state) {
	    // Change the state to AppConnect Not Available.
	    // Persistently store the state, and continue as a regular app
 
	    [self setState:DMS_ACNotAvailable];
    }

If the AppConnect library was not started, continue as a regular, non-AppConnect app.

In this case, if the dual-mode state had been persisted prior to this launch, it was either Non-AppConnect Mode, AppConnect Not Available, or Pending AppConnect Mode. If it had not been persisted, the state changed from Undecided to AppConnect Not Available.
If the AppConnect library was started and the persisted dual-mode state was AppConnect Mode:
- Wait for the -appConnectIsReady: callback method before accessing any instance properties on the AppConnect singleton.
- Continue as an AppConnect app. Regarding data encryption, if the data encryption state is Encrypted, it can use secure file I/O.
If the AppConnect library was started and the dual-mode state is AppConnect Not Available, Undecided, or Pending AppConnect Mode, wait for the AppConnect library to call the -appConnect:managedPolicyChangedTo: callback method.

The state change depends on the value of the newManagedPolicy parameter in the callback method:
- If the value ACMANAGEDPOLICY_MANAGED, the app changes to AppConnect Mode, and persistently stores the new dual-mode state.
  
  The app begins behaving as an AppConnect app. For example, it handles DLP policies, and when the data encryption state changes to Encrypted, it starts using secure file I/O
- If the value ACMANAGEDPOLICY_UNMANAGED, the app changes to Non-AppConnect Mode, and persistently stores the new dual-mode state.
  
  It calls -retire, and then stops the AppConnect library:
```
       [_ac retire];
       [_ac stop]:
       _ac = nil;
```
The app begins behaving as a regular, non-AppConnect app.

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.

Dual-mode sample app code snippets illustrating this behavior are from:
File: Policies.m
Methods: -switchToNonACMode:

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.
Sets the data encryption state to Unencrypted, since regular apps do not encrypt data. It persistently saves the state.
Persistently saves its dual-mode state as Non-AppConnect Mode.
Calls the -retire method on the AppConnect singleton object, and then stops the AppConnect library.
```
    [_ac retire];
    [_ac stop]:
    _ac = nil;
```
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.

Dual-mode sample app code snippets illustrating this behavior are from:
File: Policies.m
Methods: -attemptSwitchToACMode: and -appConnect:managedPolicyChangedTo:

The app does the following:

Changes to the Pending AppConnect Mode state, and persistently stores the state.
Starts the AppConnect library, using -startWithLaunchOptions:.
```
   [AppConnect initWithDelegate:self];
   _ac = [AppConnect sharedInstance];
   [_ac startWithLaunchOptions:nil];
```
When restarting the AppConnect library, the parameter passed to
-startWithLaunchOptions: is nil.
Waits for the AppConnect library to call -appConnect:managedPolicyChangedTo:.

When -appConnect:managedPolicyChangedTo: is called:

If the newManagedPolicy parameter has the value ACMANAGEDPOLICY_UNMANAGED:

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

The app calls -retire, and then stops the AppConnect library:
```
    [_ac retire];
    [_ac stop]:
    _ac = nil;
```
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 parameter has the value ACMANAGEDPOLICY_MANAGED:

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

If secure services are available, and the secure file I/O policy is required, the app sets the data encryption state to Encrypted. The app decides what to do with existing data. For example, the DualMode sample app encrypts all its existing notes. As the app continues, it checks the data encryption state to determine whether to use secure file I/O APIs.

Also, when changing to AppConnect Mode, 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.