App-specific configuration API details
The AppConnect for iOS API provides properties and methods that allow an app to receive app-specific configuration from the MobileIron server. For an overview of this feature, see Configuration specific to the app.
The config property
The read-only config property on the AppConnect singleton is an NSDictionary object. It contains the current key-value pairs for the app-specific configuration.
Whenever changes to the key-value pairs occur, the AppConnect library:
| 1. | updates the config property |
| 2. | calls the -appConnect:configChangedTo: method to provide your app the current configuration. |
When your app launches:
| • | Get the singleton AppConnect object and call its -startWithLaunchOptions: method. |
| • | Wait for the -appConnectIsReady: callback method before accessing the config property. |
| • | After the -appConnectIsReady: callback method is called, check the value of the config property. It contains the key-value pairs, if any, that are configured on the MobileIron server for the app. If no key-value pairs are configured, the config property is an NSDictionary object with no entries. |
| • | Apply the configuration according to your application’s requirements and logic. |
App-specific configuration methods
Your app uses the following methods to receive app-specific configuration updates and report how the app handled the updates.
The -appConnect:configChangedTo: callback method
You optionally implement this method, which is in the AppConnectDelegate protocol:
-(void) appConnect:(AppConnect *)appConnect configChangedTo:(NSDictionary *)newConfig;
Implement this method only if your app uses app-specific configuration key-value pairs that the MobileIron server administrator configures on the server Admin Portal.
When a change has occurred to the app-specific configuration on the MobileIron server, the AppConnect library:
| 1. | Sets the config property on the AppConnect object to the new NSDictionary value. |
| 2. | Calls the -appConnect:configChangedTo: method, which provides the new NSDictionary value in its parameter. |
Your app then:
| • | applies the new configuration according to your application’s requirements and logic. |
| • | calls the -configApplied:message: method. |
The -configApplied: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)configApplied:(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 app-specific configuration updates. |
Pass the value ACPOLICY_APPLIED if the app successfully handled the updates. Otherwise, pass the value ACPOLICY_ERROR. Pass the value ACPOLICY_UNSUPPORTED if your app does not support app-specific configuration. If you do not implement the -configApplied: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 app-specific configuration updates. The string is reported in the MobileIron server log files.