AppConnect for iOS Cordova Plugin overview
The AppConnect for iOS Cordova Plugin provides these capabilities to your app:
•Initializing the AppConnect library
•Getting the user’s authorization status, and receiving events about changes
•Getting app-specific configuration, and receiving events about changes
•Getting data loss prevention policies, and receiving events about changes
•Getting the version of the AppConnect library
•Allowing cached responses for URL requests that use AppTunnel with HTTP/S tunneling.
•Getting notifications of iOS active state changes due to certain control switches to and from the client app.
The AppConnectCordova Plugin JavaScript interface is defined in AppConnectCordova.js. It defines enumerations and methods for interacting with the plugin. An app also interacts with the plugin by handling events that the plugin generates.
Dual-mode app capabilities
If your AppConnect app is distributed from the Apple App Store, due to Apple App Store requirements, your app is required to work as either:
•an AppConnect app for enterprise users
•a regular app for general consumers
Such an app is called a dual-mode app. Using one code base and APIs in the AppConnect for iOS Cordova Plugin, the app determines which way to behave. Depending on the app, the functionality available as a regular app can differ significantly from the functionality available as an AppConnect app.
AppConnect apps distributed from the Apple App Store must be dual-mode apps. If you are a third-party app developer, you typically build apps for Apple App Store distribution. If you are an in-house app developer, your apps are typically distributed from the Ivanti server.
For more information, see Developing third-party dual-mode apps.
The AppConnectCordova JavaScript interface
The AppConnectCordova.js file defines the AppConnectCordova Plugin Javascript interface. This interface includes the method that you use to initialize the AppConnect library. For details, see Initialize the AppConnect library.
The AppConnectCordova Javascript interface also declares the methods that your app uses to interact with the AppConnect library. However, the app cannot interact with the AppConnect library until the AppConnect library has completed its initialization. For details about checking when the AppConnect library is ready, see:
•Wait for the AppConnect library to be ready
• AppConnect ready API details
For details of each of the AppConnectCordova interface’s methods, see:
• AppConnect ready API details
•App-specific configuration API details
•Pasteboard policy API details
•Getting the AppConnect library version
•Caching tunneled URL responses
The AppConnectCordova interface also provides methods specifically for dual-mode apps. These methods are described in Developing third-party dual-mode apps.
Event handling overview
The AppConnect Cordova Plugin generates events when it has new information to report to your app. Your app adds event listeners to its document object for these events, and provides event handlers.
Your app handles events about changes to:
•the ready status of the AppConnect library
•the user’s authorization status
•app-specific configuration
•data loss prevention policies
•upload progress for data tunneled with AppTunnel
In the event handlers, your app:
| 1. | Makes appropriate changes to its logic, display, and data. |
| 2. | In most cases, calls a method of the AppConnect Cordova interface to inform the AppConnect library about its success or failure in making the changes. |
AppConnect Cordova Plugin events
Add event listeners to the document object for these events:
|
Event name |
Description |
|
'appconnect.isReady' |
The AppConnect library has finished initializing. Your app can now access the properties and methods of the AppConnect Cordova Plugin. Handling this event is required. |
|
'appconnect.authStateChangedTo' |
The authentication state has changed. Handling this event is required. |
|
'appconnect.configChangedTo' |
The app-specific configuration settings have changed. Handling this event is optional. Handle it only if your app uses app-specific configuration. |
|
'appconnect.openInPolicyChangedTo' |
The Open In policy has changed. Handling this event is optional. Handle it only if your app uses the Open In feature. |
|
'appconnect.pasteboardPolicyChangedTo' |
The pasteboard policy has changed. Handling this event is optional. Handle it only if your app copies content to the pasteboard. |
|
'appconnect.printPolicyChangedTo' |
The print policy has changed. Handling this event is optional. Handle it only if your app is able to print. |
|
'appconnect.uploadProgressDidChange' |
Upload progress for AppTunnel data has changed. Handling this event is optional. Handle it if your app supports tunneling data with AppTunnel. |
For details about handling each event, see:
• AppConnect ready API details
•App-specific configuration API details
•Pasteboard policy API details
Event handling acknowledgments
Your app must inform the AppConnect library of your app’s success or failure in applying changes it receives in events. Depending on the type of event, your app calls one of the following methods of the AppConnectCordova interface:
AppConnectCordova.authStateApplied() AppConnectCordova.configApplied() AppConnectCordova.openInPolicyApplied() AppConnectCordova.pasteboardPolicyApplied() AppConnectCordova.printPolicyApplied()
No event acknowledgment method exists for 'appconnect.isReady'.
Each event acknowledgment method takes two parameters:
•an AppConnectCordova.ACPolicyState enumeration value:
AppConnectCordova.prototype.ACPolicyState = {
UNSUPPORTED: 0, // The policy is not supported by this application
APPLIED: 1, // The policy was applied successfully
ERROR: 2 // An error occurred applying the policy
}
Typically, you pass either APPLIED or ERROR. If you do not call the acknowledgment method for one of the optional events, the AppConnect Cordova Plugin behaves as if your app had called the method with UNSUPPORTED.
•a string value, which is a message explaining the AppConnectCordova.ACPolicyState value.
Typically, you use this string to report the reason the app failed to apply the update. The string is reported in the Ivanti server log files.
Two other optional parameters are also in the function definition, but you should not pass these parameters.