App-specific configuration callback methods

Overview of app-specific configuration from the Ivanti server

Handling app-specific configuration from the Ivanti server requires some application development before wrapping the app. If you do not use this feature, the app continues to set up its configuration as it always has.

Typically, wrapped apps do not use this feature. However, if you have application developer resources, you can take advantage of this feature.

You determine the app-specific configuration that your app requires from the Ivanti server. Examples are:

the address of a server that the app interacts with
whether particular features of the app are enabled for the user
user-related information from LDAP, such as the user’s ID and password
certificates for authenticating the user to the server that the app interacts with

Each configurable item is a key-value pair. Each key and value is a string. An Ivanti server administrator specifies on the server the key-value pairs for each app. The administrator applies the appropriate set of key-value pairs to a set of devices. Sometimes more than one set of key-value pairs exists on the server for an app if different users require different configurations. For example, the administrator can assign a different server address to users in Europe than to users in the United States.

When the value is a certificate, the value contains the base64-encoded contents of the certificate, which is a SCEP or PKCS-12 certificate. If the certificate is password encoded, the Ivanti server automatically sends another key-value pair. The key’s name is the string <name of key for certificate>_MI_CERT_PW. The value is the certificate’s password.

Methods for receiving app-specific configuration from the Ivanti server

To receive app-specific configuration from the Ivanti server, the developer implements one or both of the following callback methods on the class that implements the UIApplicationDelegate protocol:

In Objective-C:

-(NSString *)appConnectConfigIs:(NSDictionary *)config;

-(NSString *)appConnectConfigChangedTo:(NSDictionary *)config;

In Swift:

@objc func appConnectConfigIs(_ config: [String : Any]) -> String?

@objc func appConnectConfigChangedTo(_ config: [String : Any]) -> String?

Both methods:

Have a config parameter.

The parameter is an NSDictionary object which contains the current key-value pairs for the app-specific configuration. The app applies the values according to its requirements and logic.
Return the value nil if the configuration was successfully applied. Otherwise, return a string that describes the error that occurred in applying the configuration.

When to use -appConnectConfigIs: versus -appConnectConfigChangedTo:

When to use -appConnectConfigIs:

Use -appConnectConfigIs: to find out what the app-specific configuration is. The AppConnect library calls -appConnectConfigIs: when:

the app is launched or relaunched.
the configuration changes on the Ivanti server.

When using -appConnectConfigIs:, the app can depend on the configuration values being available in memory at any time.

Some examples for using -appConnectConfigIs: to get app-specific configuration from the Ivanti server:

User permissions that are accessed throughout the life of the app.
A server address that the app uses to connect to a server, or reconnect after losing network connectivity.

When to use -appConnectConfigChangedTo:

Use -appConnectConfigChangedTo: when the app needs to take some action when the app-specific configuration changes. The AppConnect library calls -appConnectConfigChangedTo: when the configuration changes on the Ivanti server.

When using -appConnectConfigChangedTo:, the app knows when configuration values change, and should take the appropriate action immediately. The configuration values are not available in memory after an app relaunch, but because the app already took the necessary actions, the unavailability does not matter.

Some examples for using-appConnectConfigChangedTo: to receive changes to the Ivanti server app-specific configuration are:

A setting indicating whether the user can access certain data.

If access is denied, the app removes that data immediately. Once the app has removed the data, the app will not use the setting again. Therefore, the setting’s availability in memory does not matter.
User registration information

If the app requires that the user registers to a server one time, the app registers the user when it receives the registration information. Once registered, the app will not use the registration information again. Therefore, the information’s availability in memory does not matter.

Details about when each method is called

The following table provides the details about when each method is called, with the differences in behavior shown in bold.

Action	-appConnectConfigChangedTo:	-appConnectConfigIs:
The app is launched for the first time and the Ivanti server has app-specific configuration. In this case, the app-specific configuration changes from nil to some values.	Called	Called
The app is launched for the first time and the Ivanti server has no app-specific configuration.	Not called	Not called
The app is re-launched after being terminated and the configuration has not changed since the app last ran. (Termination is due to, for example, a force-close by the user, an iOS termination, or an app crash).	Not called	Called
The app is re-launched after being terminated and the configuration has changed since the app last ran.	Called	Called
A change has occurred to the app-specific configuration on the Ivanti server while the app is running.	Called	Called

Handling app-specific configuration in Xamarin apps

Wrapped Xamarin apps can handle app-specific configuration from the Ivanti server.

The developer implements one or both of the following methods in the UIApplicationDelegate class or subclass:

[Export ("appConnectConfigIs:")]
 
public string AppConnectConfigIs (NSDictionary config) {
 
	// The config parameter contains the current key-value pairs for the 
	// app-specific configuration.
	// Apply the configuration according to the application’s requirements and logic.
 
	return null; // Return null on success. If a error occurs, return a string 
		     // describing the error.
}
 
[Export ("appConnectConfigChangedTo:")]
 
public string AppConnectConfigChangedTo (NSDictionary config) {
 
	// The config parameter contains the current key-value pairs for the 
       // app-specific configuration.
	// Apply the configuration according to the application’s requirements and logic.
 
	return null; // Return null on success. If a error occurs, return a string 
		     // describing the error.
}