Open In policy API details

The AppConnect for iOS API provides properties and methods that allow an app to handle its Open In policy as determined by the MobileIron 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, or an app’s extension, or the native iOS mail app. 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, an app uses the UIDocumentInteractionController, QLPreviewController (which in turn uses UIDocumentInteractionController), and UIActivityViewController classes. 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 properties
• Open In policy methods
• 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:

• ACOPENINPOLICY_AUTHORIZED -- The application is allowed to use Open In.
• ACOPENINPOLICY_UNAUTHORIZED -- The application is not allowed to use Open In.
• ACOPENINPOLICY_WHITELIST -- The application is allowed to use Open In to send documents only to apps in the whitelist. To put the iOS native email app in the whitelist, the whitelist must contain both of these bundle IDs: com.apple.UIKit.activity.Mail and com.apple.mobilemail.
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 UIActivityViewController to perform Open In functionality. Because of iOS implementation, the AppConnect library cannot determine which app the end user selects, and therefore, whether it 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 for each Open In status. It assumes you use UIDocumentInteractionController, and do not use UIActivityViewController.

 

Table 1. Open In actions taken by the AppConnect library and your app

Open In status

AppConnect library actions

Your app’s actions

AUTHORIZED

The AppConnect library performs no actions on Open In behavior.

Enable user interfaces, if any, that give the user the option to use Open In.

For example, if your app presents a menu item for Open In, the menu item should be enabled.

UNAUTHORIZED

If a user taps on any of the apps:

• the AppConnect library substitutes a dummy file with a mangled name. Therefore, the target app cannot open the file. Target app error handling varies. For example, some apps display an error pop-up.
• The AppConnect library also calls this callback method if your app implemented it:

-appConnect:openInAttemptedWhenACOpenInPolicyBlocked:

• Disable user interfaces, if any, that give the user the option to use Open In. For example, if your app presents a menu item for Open In, the menu item should be disabled.

By disabling such user interfaces, your app does not give the end user the impression that Open In is possible when the AppConnect library has disabled it.

• Implement the callback method

-appConnect:
openInAttemptedWhenACOpenInPolicyBlocked:

In the method, notify the user that Open In is not allowed.

Note that if you disabled all Open In user interfaces, this method will not be called.

WHITELIST

If a user taps on an app that is not in the whitelist:

• the AppConnect library substitutes a dummy file with a mangled name. Therefore, the target app cannot open the file. Target app error handling varies. For example, some apps display an error pop-up.
• The AppConnect library also calls this callback method if your app implemented it:

-appConnect:openInAttemptedWhenACOpenInPolicyBlocked:
• Enable user interfaces, if any, that give the user the option to use Open In. For example, if your app presents a menu item for Open In, the menu item should be enabled.
• Implement the callback method

-appConnect:
openInAttemptedWhenACOpenInPolicyBlocked:

In the method, notify the user that Open In is not allowed to the selected app.

The ACOpenInPolicy enumeration

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

typedef enum {
    ACOPENINPOLICY_UNAUTHORIZED =  0, // The application may not use Open In.
    ACOPENINPOLICY_AUTHORIZED   =  1, // The application may use Open In.
    ACOPENINPOLICY_WHITELIST    =  2, // The application may only use Open In to send
                                      // documents to applications in the whitelist.
} ACOpenInPolicy;

The openInPolicy and openInWhitelist properties

The following read-only properties on the AppConnect singleton relate to the Open In policy:

Table 2. Open In properties on the AppConnect singleton

Property

Description

openInPolicy

An ACOpenInPolicy value that indicates the current status of the Open In policy for the app.

openInWhitelist

An NSSet object that contains NSString objects. Each string is the bundle ID of an app in the whitelist. 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.

NOTE: When the Open In policy on the MobileIron 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.

When your app launches:

• Get the singleton AppConnect object and call its -startWithLaunchOptions: method.
• Wait for the -appConnectIsReady: callback method before accessing the openInPolicy and openInWhitelist properties.

After the -appConnectIsReady: callback method is called, enable or disable user interfaces, if any, that give the user the option to use the Open In feature, depending on the openInPolicy property value.

Whenever changes to the Open In policy or whitelist occur, the AppConnect library:

1. Updates the properties.
2. Calls the -openInPolicyChangedTo:whitelist: method to provide your app the current information.

Open In policy methods

Your app uses the following methods to receive Open In policy updates and to report how the app handled the updates.

• The -appConnect:openInPolicyChangedTo:whitelist: callback method
• The -openInPolicyApplied:message: acknowledgment method
• The -appConnect:openInAttemptedWhenACOpenInPolicyBlocked: callback method
• The -appConnect:openURLAttemptedWhenUnauthorizedForURL: callback method

The -appConnect:openInPolicyChangedTo:whitelist: callback method

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

-(void) appConnect:(AppConnect *)appConnect openInPolicyChangedTo:
           (ACOpenInPolicy)newOpenInPolicy whitelist:(NSSet *)newWhitelist;

Implement this method only if your app uses the Open In feature.

When a change has occurred to the Open In policy on the MobileIron server, the AppConnect library:

1. Sets the openInPolicy and openInWhitelist properties on the AppConnect object to the new values.
2. Calls the -appConnect:openInPolicyChangedTo:whitelist method, which provides the new values in its parameters.

Your app then:

• Enable or disable user interfaces, if any, that give the user the option to use the Open In feature, depending on the openInPolicy property value.
• calls the -appConnect:openInPolicyApplied:message: method.

The -openInPolicyApplied:message: acknowledgment method

After your app processes the information provided in the callback method, it must call this acknowledgment method on the AppConnect singleton:

-(void)openInPolicyApplied:(ACPolicyState)policyState message:(NSString *)message;

Your app passes the following parameters to this method:

• the ACPolicyState value that represents the success or failure of handling the Open In policy update.

Pass the value ACPOLICY_APPLIED if the app successfully handled the update. Otherwise, pass the value ACPOLICY_ERROR. Pass the value ACPOLICY_UNSUPPORTED if your app does not support the Open In feature. If you do not implement the -openInPolicyApplied:message method, the AppConnect singleton behaves as if you passed it ACPOLICY_UNSUPPORTED.

• an NSString explaining the ACPolicyState value.

Typically, you use this string to report the reason the app failed to apply the Open In policy update. The string is reported in the MobileIron server log files.

The -appConnect:openInAttemptedWhenACOpenInPolicyBlocked: callback method

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

-(void) appConnect:(AppConnect *)appConnect openInAttemptedWhenACOpenInPolicyBlocked:
                                 (ACOpenInPolicy)OpenInPolicy;

This method is useful because even when the Open In policy is ACOPENINPOLICY_UNAUTHORIZED or ACOPENINPOLICY_WHITELIST, when an app makes an Open In request, iOS still displays all apps that support the document type. An end user who taps an app sometimes expects the Open In operation to be successful. You can implement this method to alert the end user that Open In is not allowed for the selected app.

Note that this method is also called for Open In requests to the iOS native email app when the policy is ACOPENINPOLICY_UNAUTHORIZED or ACOPENINPOLICY_WHITELIST and the native email app is not on the whitelist. For example, with these policy settings, this method is called when the device user taps a :mailTo link in a UIWebView, WKWebView, or UITextView, or when the app attempts to display a MFMailComposeViewController.

For example:

-(void) appConnect:(AppConnect *)appConnect 
	   openInAttemptedWhenACOpenInPolicyBlocked: (ACOpenInPolicy)OpenInPolicy { 
 
    UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"Open In not allowed" 
	                  message:@"You are not allowed to share a document with this app." 
	                  delegate:nil cancelButtonTitle:@"OK" otherButtonTitles: nil]; 
    [alert show]; 
}

The -appConnect:openURLAttemptedWhenUnauthorizedForURL: callback method

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

-(void) appConnect:(AppConnect *)appConnect openURLAttemptedWhenUnauthorizedForURL:
                                 (NSURL *)openURL;

This method is called when your app has called -openURL: with the mailto scheme and either:

• the Open In policy is ACOPENINPOLICY_UNAUTHORIZED
• the Open In policy is ACOPENINPOLICY_WHITELIST, and the whitelist does not contain the bundle ID of an app that can handle the URL, such as the native iOS email app.

However, if the AppConnect app Email+ is installed on the device, it is opened and the callback method is not called.

Use this method to notify the end user that opening an app to handle the request is not allowed due to the Open In policy.

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

NOTE: The MobileIron 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.