Pasteboard policy API details
The AppConnect for iOS API provides properties and methods that allow an app to handle its pasteboard policy as determined by the MobileIron server. For an overview of this feature, see Data loss prevention policies.
This policy determines whether your app is allowed to copy content to the pasteboard. This policy does not impact whether your app is allowed to paste content from the pasteboard into your app.
The ACPasteboardPolicy enumeration
The ACPasteboardPolicy enumeration provides the possible pasteboard statuses for the app:
typedef enum {
ACPASTEBOARDPOLICY_UNAUTHORIZED = 0, // The application cannot write data
// to the pasteboard.
// The AppConnect library enforces this status
// and ensures that the app cannot modify the
// pasteboard contents.
ACPASTEBOARDPOLICY_AUTHORIZED = 1, // The application may write data to the pasteboard
// which gets shared among all apps.
// (Both AppConnect and non-AppConnect apps
// can read this data).
ACPASTEBOARDPOLICY_SECURECOPY = 2 // The application may write data to the general
// pasteboard which is shared with authorized
// AppConnect apps.
// The AppConnect library implements the underlying
// technology so that the data written to the
// general pasteboard by one AppConnect app is only
// readable by authorized AppConnect apps.
} ACPasteboardPolicy;
Handle the pasteboard policy status as follows:
|
•
|
Both ACPASTEBOARDPOLICY_AUTHORIZED and ACPASTEBOARDPOLICY_SECURECOPY indicate that copying content to the pasteboard is allowed. The AppConnect library handles making sure all apps or only AppConnect apps can paste the data. When the value is ACPASTEBOARDPOLICY_SECURECOPY, the AppConnect library encrypts the data copied to the pasteboard, and decrypts the data when it is pasted to another AppConnect app. |
|
•
|
The status ACPASTEBOARDPOLICY_UNAUTHORIZED indicates that writing data to the pasteboard is not allowed. The AppConnect library enforces the status ACPASTEBOARDPOLICY_UNAUTHORIZED. Therefore, with this status, even if you use an API to write to the pasteboard, the data is not written. |
Exceptions to this rule exist. For some iOS APIs, such as QLPreviewController, it is not possible to prevent data from being written to the pasteboard. If your app uses such APIs, when the status is ACPASTEBOARDPOLICY_UNAUTHORIZED, change your app’s behavior so that it does not use that API. However, for some apps, changing the behavior is not possible, due to, for example, an unacceptable degradation in the app’s capabilities. In that case, your app should indicate that it does not support the pasteboard policy, as described in The -pasteboardPolicyApplied:message: acknowledgment method.
Although the AppConnect library does not allow writing data to the pasteboard, your app should disable special user interfaces, if any, that it uses for copying content to the pasteboard. By disabling such user interfaces, your app does not give the end user the impression that copying is possible when the AppConnect library has disabled it.
Impact on the pasteboard policy of secure services availability
The pasteboard policy ACPASTEBOARDPOLICY_SECURECOPY depends on secure services being available. If secure services are not available and the pasteboard policy is ACPASTEBOARDPOLICY_SECURECOPY:
|
•
|
Writing content to the pasteboard (copying) fails. No data is written. |
|
•
|
Reading content from the pasteboard (pasting) reads unsecured content, if any. |
The pasteboardPolicy property
The read-only pasteboardPolicy property on the AppConnect singleton contains an ACPasteboardPolicy value. The value reflects the current status of the pasteboard policy for the app.
The AppConnect library enables or disables the app’s ability to copy content to the pasteboard depending on the pasteboardPolicy value:
|
•
|
Copying is enabled for ACPASTEBOARDPOLICY_AUTHORIZED. |
|
•
|
Copying is disabled for ACPASTEBOARDPOLICY_UNAUTHORIZED. |
|
•
|
Copying is enabled for ACPASTEBOARDPOLICY_SECURECOPY if the secureServicesAvailability property has the value ACSECURESERVICESAVAILABILITY_AVAILABLE. |
|
•
|
Copying is disabled for ACPASTEBOARDPOLICY_SECURECOPY if the secureServicesAvailability property has the value ACSECURESERVICESAVAILABILITY_UNAVAILABLE. |
When your app launches:
|
1.
|
Get the singleton AppConnect object and call its
-startWithLaunchOptions: method. |
|
2.
|
Wait for the -appConnectIsReady: callback method before accessing the pasteboardPolicy property. |
|
3.
|
After the -appConnectIsReady: callback method is called, depending on the pasteboardPolicy value, disable or enable special user interfaces, if any, that the app uses for copying content to the pasteboard. Although the AppConnect library enables or disables writing data to the pasteboard, your app should not give the end user the impression that copying is possible when the AppConnect library has disabled it. |
Whenever the policy changes, the AppConnect library:
|
1.
|
updates the pasteboardPolicy property. |
|
2.
|
calls the -appConnect:pasteboardPolicyChangedTo: method to provide your app the current pasteboard policy. |
Pasteboard policy methods
Your app uses the following methods to receive pasteboard policy updates and to report how the app handled the updates.
The -appConnect:pasteboardPolicyChangedTo: callback method
You optionally implement this method, which is in the AppConnectDelegate protocol:
-(void) appConnect:(AppConnect *)appConnect pasteboardPolicyChangedTo:
(ACPasteboardPolicy)newPasteboardPolicy;
Implement this method only if your app copies content to the pasteboard. This policy does not impact whether your app is allowed to paste content from the pasteboard into your app.
When a change has occurred to the pasteboard policy on the MobileIron server, the AppConnect library:
|
1.
|
Sets the pasteboardPolicy property on the AppConnect object to the new ACPasteboardPolicy value. |
|
2.
|
Disables or enables copying to the pasteboard as follows: |
|
-
|
Enables copying for ACPASTEBOARDPOLICY_AUTHORIZED. |
|
-
|
Disables copying for ACPASTEBOARDPOLICY_UNAUTHORIZED. |
|
-
|
Enables copying for ACPASTEBOARDPOLICY_SECURECOPY if the secureServicesAvailability property has the value ACSECURESERVICESAVAILABILITY_AVAILABLE. |
|
-
|
Disables copying for ACPASTEBOARDPOLICY_SECURECOPY if the secureServicesAvailability property has the value ACSECURESERVICESAVAILABILITY_UNAVAILABLE. |
|
3.
|
Calls the appConnect:pasteboardPolicyChangedTo: method, which provides the new ACPasteboardPolicy value in its parameter. |
Your app then:
|
•
|
Disables or enables special user interfaces, if any, that the app uses for copying content to the pasteboard. Although the AppConnect library enables or disables writing data to the pasteboard, your app should not give the end user the impression that copying is possible when the AppConnect library has disabled it. |
|
•
|
calls the -pasteboardPolicyApplied:message: method. |
The -pasteboardPolicyApplied: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)pasteboardPolicyApplied:(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 pasteboard 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 copying content to the pasteboard. If you do not implement the -pasteboardPolicyApplied: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 pasteboard policy update. The string is reported in the MobileIron server log files.
The -appConnect:copyAttemptedWhenUnauthorized: callback method
You optionally implement this method, which is in the AppConnectDelegate protocol:
-(void) appConnect:(AppConnect *)appConnect copyAttemptedWhenUnauthorized:
(ACPasteboardPolicy)pasteboardPolicy;
This method is useful because when the pasteboard policy is ACPASTEBOARDPOLICY_UNAUTHORIZED, iOS behavior still causes the copy button to display. An end user who taps the copy button sometimes expects that text has been copied. You can implement this method to alert the end user that no text has been copied.
For example:
-(void) appConnect:(AppConnect *)appConnect copyAttemptedWhenUnauthorized:
(ACPasteboardPolicy)pasteboardPolicy {
UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"Copy not allowed"
message:@"You are not allowed to copy from this app."
delegate:nil cancelButtonTitle:@"OK" otherButtonTitles: nil];
[alert show];
}