Open From policy API details

IMPORTANT: T Open From does not work on iOS 13 devices.

The AppConnect for iOS API provides properties and methods that allow an app to handle its Open From 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 From, it can receive a document shared from another app (or another app’s extension) that uses the Open In iOS feature.

• Overview of Open From handling
• The ACOpenFromPolicy enumeration
• The openFromPolicy and openFromWhitelist properties
• Open From policy methods
• Open From policy API details

Overview of Open From handling

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

The possible status values are:

• ACOPENFROMPOLICY_AUTHORIZED -- The app is allowed to receive documents shared by any app that uses Open In.
• ACOPENFROMPOLICY_UNAUTHORIZED -- The app is not allowed to receive documents shared by any app that uses Open In.
• ACOPENFROMPOLICY_WHITELIST -- The app is allowed to receive documents shared by another app using Open In only if the other app is 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:  

When an app makes an Open In request, iOS always displays all the apps that support the document type, regardless of:

• the requesting app's Open In policy status if it is an AppConnect app
• the receiving app's Open From policy status if it is an AppConnect app

Although the AppConnect library enforces the Open From policy, this iOS behavior means that your app might want to keep the user informed of failed attempts. The following table summarizes the behavior of the AppConnect library and recommended actions for your app relating to Open From.

 

Table 1. Open From 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 From behavior.

None

UNAUTHORIZED

The AppConnect library does not allow another app to Open In to your app.

Additionally, if a user chooses to Open In to your app, the AppConnect library calls this callback method if your app implemented it.

-appConnect:openFromAttemptedWhenACOpenFromPolicyBlocked:

Implement the callback method. In the method, notify the user that using Open In from the specified app to your app is not allowed.

WHITELIST

The AppConnect library does not allow an app that is not on the whitelist to Open In to your app.

Additionally, if a user chooses to Open In to your app from an app that is not in the whitelist, the AppConnect library calls this callback method if your app implemented it:

-appConnect:openFromAttemptedWhenACOpenFromPolicyBlocked:

Implement the callback method. In the method, notify the user that Open From the specified app is not allowed.

The ACOpenFromPolicy enumeration

The ACOpenFromPolicy enumeration provides the possible Open From statuses for the app:

typedef enum {
    ACOPENFROMPOLICY_UNAUTHORIZED =  0, // The app is allowed to receive documents shared by 
                                        // any app that uses Open In.
    ACOPENFROMPOLICY_AUTHORIZED   =  1, // The app is not allowed to receive documents shared 
                                        // by any app that uses Open In.
    ACOPENFROMPOLICY_WHITELIST    =  2, // The app is allowed to receive documents shared by 
                                        // another app using Open In only if the other app 
                                        // is in the whitelist.
                                     
} ACOpenFromPolicy;

The openFromPolicy and openFromWhitelist properties

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

Table 2. Open From properties on the AppConnect singleton

Property

Description

openFromPolicy

An ACOpenFromPolicy value that indicates the current status of the Open From policy for the app.

openFromWhitelist

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 from which your app is allowed to receive documents.

Because the AppConnect library enforces Open From from only the whitelisted apps, your app uses this list only if it wants to inform the user about the list.

NOTE: When the Open From policy on the MobileIron server specifies “All AppConnect apps”, the Open From status value is ACOPENFROMPOLICY_WHITELIST. The openFromWhitelist 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 openFromPolicy and openFromWhitelist properties.

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

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

Open From policy methods

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

• The -appConnect:openFromPolicyChangedTo:whitelist: callback method
• The -openFromPolicyApplied:message: acknowledgment method
• The -appConnect:openFromAttemptedWhenACOpenFromPolicyBlocked: callback method

The -appConnect:openFromPolicyChangedTo:whitelist: callback method

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

-(void) appConnect:(AppConnect *)appConnect openFromPolicyChangedTo:
           (ACOpenInPolicy)newOpenFromPolicy whitelist:(NSSet<NSString *>)newWhitelist;

Implement this method only if:

  • your app handles documents from other apps using Open In, and
  • your app uses the Open From policy value or whitelist in some way, such as displaying information about it to the user. The AppConnect library enforces the policy.

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

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

Your app then:

• Can access the new values. The app can use them, for example, to inform the end user about allowed Open From apps.
• calls the -appConnect:openFromPolicyApplied:message: method.

The -openFromPolicyApplied: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)openFromPolicyApplied:(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 From 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 From 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 From policy update. The string is reported in the MobileIron server log files.

The -appConnect:openFromAttemptedWhenACOpenFromPolicyBlocked: callback method

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

-(void) appConnect:(AppConnect *)appConnect openFromAttemptedWhenACOpenFromPolicyBlocked:
                                 (ACOpenFromPolicy)OpenFromPolicy
                                 sourceApplication:(NSString *)sourceApplicationId;

This method is useful because even when the Open From policy is ACOPENFROMPOLICY_UNAUTHORIZED or ACOPENFROMPOLICY_WHITELIST, when another app makes an Open In request, iOS still displays all apps that support the document type. An end user who taps an app expects the Open In operation to be successful. You can implement this method to alert the end user that your app is not allowed to receive documents from the other app.