Open In policy API details

The AppConnect Cordova Plugin provides an enumeration, an event, and methods that allow an app to handle its Open In policy as determined by the Ivanti server. For an overview of this feature, see Data loss prevention policies.

Specifically, when an app is allowed to use Open In, it can share a document with another app on the device. This capability:

•is usually presented to the user as an Open In menu item.

•includes sending documents or document portions by encoding them in custom URLs handled by other applications.

Internally, a Cordova app can use either the UIDocumentInteractionController or UIActivityViewController classes from Objective-C. The class which the app uses impacts Open In handling as described in Overview of Open In handling.

•Overview of Open In handling

•The ACOpenInPolicy enumeration

•The openInPolicy() and openInWhitelist() methods

•The 'appconnect.openInPolicyChangedTo' event

•Event handler for 'appConnect.openInPolicyChangedTo' event

•The openInPolicyApplied() method

•Info.plist key related to the Open In policy

Overview of Open In handling

The behavior of the AppConnect library, and the actions your app takes, depend on the Open In policy status.

The possible status values are:

• AUTHORIZED -- The application is allowed to use Open In.

• UNAUTHORIZED -- The application is not allowed to use Open In.

• WHITELIST -- The application is allowed to use Open In to send documents only to apps in the whitelist.

IMPORTANT:

• Regardless of the Open In policy status, when an app makes an Open In request, iOS always displays all the apps that support the document type.

• Do not use the Objective-C class UIActivityViewController to perform Open In functionality. For example, make sure any Cordova plugin you use to provide the iOS Open In capability does not use UIActivityViewController. Because of iOS implementation, the AppConnect library cannot determine which app the end user selects, and therefore, whether the app is in the whitelist. To ensure security, the AppConnect library does not allow Open In to any app when the Open In policy is ACOPENINPOLICY_WHITELIST and the class used is UIActivityViewController.

The following table summarizes the behavior of the AppConnect library and the actions your app takes. It assumes you use UIDocumentInteractionController, and do not use UIActivityViewController.

The ACOpenInPolicy enumeration

The AppConnectCordova.ACOpenInPolicy enumeration provides the possible Open In statuses for the app:

AppConnectCordova.prototype.ACOpenInPolicy = {
    UNAUTHORIZED:  0, // The application may not use Open In.
    AUTHORIZED:    1  // The application may use Open In.
    WHITELIST:     2  // The application may only use Open In to send 
                      // documents to applications in the whitelist.
}

The openInPolicy() and openInWhitelist() methods

OpenInPolicy() method

The following method returns the current status of the Open In policy for the app:

AppConnectCordova.openInPolicy()

Return value: An AppConnectCordova.ACPOpenInPolicy enumeration value.

OpenInWhitelist() method

The following method returns the current Open In whitelist for the app. The whitelist is the set of apps to which your app is allowed to send documents. Because the AppConnect library enforces Open In to only the whitelisted apps, your app uses this list only if it wants to inform the user about the list.

AppConnectCordova.openInWhitelist()

Return value: An array. Each array element is a string which is the bundle ID of an app in the whitelist.

When the Open In policy on the Ivanti server specifies “All AppConnect apps”, the Open In status value is ACOPENINPOLICY_WHITELIST. The openInWhitelist lists all the currently authorized AppConnect apps. Therefore, your app handles the “All AppConnect apps” server setting the same way it handles the “whitelist” server setting.

For example:

["com.somecompany.someapp","com.anothercompany.anotherapp","com.thatcompany.thatapp"]

Calling OpenInPolicy() and OpenInWhitelist() when your app launches

When your app launches:

Method return values after updates to Open In policy

On any updates to the Open In policy while the app is running, the AppConnect Cordova Plugin generates the 'appconnect.OpenInPolicyChangedTo' event. Subsequent calls to the AppConnectCordova.openInPolicy() and AppConnectCordova.openInWhitelist() methods return the updated Open In policy and whitelist.

The 'appconnect.openInPolicyChangedTo' event

The AppConnect Cordova Plugin generates the 'appconnect.openInPolicyChangedTo' event when the Open In policy or whitelist changes after the plugin initialization is completed.

The event object passed to the event handler contains:

["com.somecompany.someapp","com.anothercompany.anotherapp"]

Event handler for 'appConnect.openInPolicyChangedTo' event

When a change has occurred to the Open In policy or whitelist on the Ivanti server, the AppConnect Cordova Plugin:

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

document.addEventListener('appconnect.openInPolicyChangedTo',
                           this.onOpenInPolicyChangedTo, false);

Add this event listener only if your app uses the Open In feature.

Your app handles the new status as follows:

The openInPolicyApplied() method

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

AppConnectCordova.openInPolicyApplied(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 Open In policy.

Pass the value APPLIED if the app successfully handled the new policy. Otherwise, pass the value ERROR. Pass the value UNSUPPORTED if your app does not support the Open In feature. If you do not implement an event handler for the 'appconnect.openInPolicyChangedTo' 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 new Open In policy. The string is reported in the Ivanti server log files.

Info.plist key related to the Open In policy

Your app can override the Open In policy when the policy blocks the iOS native email app when the app uses OpenURL with the mailto: scheme. Overriding the Open In policy for this scenario means that the iOS native email app is opened even though the Open In policy is one of the following:

•ACOPENINPOLICY_UNAUTHORIZED

•ACOPENINPOLICY_WHITELIST, and the whitelist does not contain the bundle IDs of the native iOS email app.

To override the Open In policy for this scenario, add the key MI_AC_DISABLE_SCHEME_BLOCKING with the value YES in the MI_APP_CONNECT dictionary in the app’s Info.plist.

The Ivanti server administrator can also override the Open In policy for this scenario by adding the key MI_AC_DISABLE_SCHEME_BLOCKING with the value true to the app’s app-specific configuration.