Pasteboard policy API details

The AppConnect Cordova Plugin provides an enumeration, an event, and methods that allow an app to handle its pasteboard policy as determined by the Ivanti 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 AppConnectCordova.ACPasteboardPolicy enumeration provides the possible pasteboard statuses for the app:

AppConnectCordova.prototype.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.
 
    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).
 
    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.
                     // If the app is not authorized, or if the device user has not
                     // entered the AppConnect passcode when required, writing to the
                     // general pasteboard will fail, and reading from
                     // it will read unsecured content, if any.
}

Handle the pasteboard policy status as follows:

•Both AUTHORIZED and 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 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 UNAUTHORIZED indicates that writing data to the pasteboard is not allowed. The AppConnect library enforces the status UNAUTHORIZED. Therefore, with this status, even if you use an API to write to the pasteboard, the data is not written.

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.

iOS behavior still causes the copy button to display, which can cause an end user who taps the copy button to expect that text has been copied.

Requirements for successful secure copy to pasteboard

The pasteboard policy SECURECOPY means that the AppConnect library encrypts and decrypts pasteboard data. However, this encryption requires that:

•The app is authorized.

•The device user has entered the AppConnect passcode (or Touch ID/Face ID), if the Ivanti server administrator required one.

If either of these requirements are not true when the pasteboard policy is 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() method

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

AppConnectCordova.pasteboardPolicy()

Return value: An AppConnectCordova.ACPasteboardPolicy enumeration value.

Calling pasteboardPolicy() when your app launches

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

•Copying is disabled for UNAUTHORIZED.

•Copying is enabled for SECURECOPY, unless the app is unauthorized or the user has not entered a required AppConnect passcode.

When your app launches:

Upon receiving the Cordova 'deviceready' event, call the method AppConnectCordova.initialize().

Wait for the AppConnectCordova event 'appconnect.isReady' before calling the AppConnectCordova.pasteboardPolicy() method.

In the event handler for the 'appconnect.isReady' event, depending on the AppConnectCordova.ACPasteboardPolicy value returned from AppConnectCordova.pasteboardPolicy(), 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.

pasteboardPolicy() return value after updates to pasteboard policy

On any updates to the pasteboard policy while the app is running, the AppConnect Cordova Plugin generates the 'appconnect.pasteboardPolicyChangedTo' event. Subsequent calls to the AppConnectCordova.pasteboardPolicy() method returns the updated pasteboard policy.

The 'appconnect.pasteboardPolicyChangedTo' event

The AppConnect Cordova Plugin generates the 'appconnect.pasteboardPolicyChangedTo' event when the pasteboard policy changes after the plugin initialization is completed.

The event object passed to the event handler contains:

Event object properties	Description
newPasteboardPolicy	An AppConnectCordova.ACPasteboardPolicy enumeration value

Event handler for 'appConnect.pasteboardPolicyChangedTo' event

When a change has occurred to the pasteboard policy on the Ivanti server, the AppConnect Cordova Plugin:

Stores the new AppConnectCordova.ACPasteboardPolicy value so that subsequent calls to the AppConnectCordova.pasteboardPolicy() method return the updated policy.

Disables or enables copying to the pasteboard as follows:

Enables copying for AUTHORIZED.

Disables copying for UNAUTHORIZED.

Enables copying SECURECOPY, unless the app is unauthorized or the user has not entered a required AppConnect passcode..

Generates the 'appconnect.pasteboardPolicyChangedTo' event.

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

document.addEventListener('appconnect.pasteboardPolicyChangedTo',
                           this.onPasteboardPolicyChangedTo, false);

Add this event listener 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.

Your app handles the new status as follows:

New status	App actions
UNAUTHORIZED	Disables special user interfaces, if any, that the app uses for copying content to the pasteboard. Although the AppConnect library 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 AppConnectCordova.pasteboardPolicyApplied() method.
AUTHORIZED or SECURECOPY	Enables special user interfaces, if any, that the app uses for copying content to the pasteboard. Calls the AppConnectCordova.pasteboardPolicyApplied() method.

New status

App actions

UNAUTHORIZED

Disables special user interfaces, if any, that the app uses for copying content to the pasteboard. Although the AppConnect library 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 AppConnectCordova.pasteboardPolicyApplied() method.

AUTHORIZED or SECURECOPY

Enables special user interfaces, if any, that the app uses for copying content to the pasteboard.
Calls the AppConnectCordova.pasteboardPolicyApplied() method.

The pasteboardPolicyApplied() method

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

AppConnectCordova.prototype.pasteboardPolicyApplied(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 pasteboard 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 copying content to the pasteboard. If you do not implement an event handler for the 'appconnect.pasteboardPolicyChangedTo' 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 pasteboard policy. The string is reported in the Ivanti serverlog files.