Getting started tasks

Objective-C apps: Follow the instructions in Before you begin adding the AppConnect SDK to your app. Then follow the instructions in either First-time use of SDK in your app or Task lists for upgrading the SDK in your app.

Swift apps: Follow the instructions in Before you begin adding the AppConnect SDK to your app. Then follow the instructions in Using the AppConnect framework in a Swift app.

Xamarin apps: Follow the instructions in Before you begin adding the AppConnect SDK to your app. Then follow the instructions in Developing AppConnect Apps with Xamarin .

Once you have completed these tasks, your app is ready to use the AppConnect for iOS API to, for example, enforce MobileIron server settings and apply app-specific configurations from the MobileIron server.

NOTE: If your app is a Cordova app, use the AppConnect for iOS Cordova Plugin, described in the MobileIron AppConnect for iOS Cordova Plugin Developers Guide.

Before you begin adding the AppConnect SDK to your app

  • Download the AppConnect for iOS SDK.

    Download the latest version of the AppConnect for iOS SDK ZIP file to your app’s Xcode project folder or other convenient location. The ZIP file is available at help.mobileiron.com in the Software tab.

    The ZIP file is named AppConnectiOSSDK_V<version>_<build>.zip where:

    • <version> is the version number of the SDK
    • <build> is the build number of the SDK.

  • Verify required product versions.

    Be sure you have the required product versions for working with apps built with the AppConnect for iOS SDK.

    See Product versions required .

  • Support fast app switching.

    Make sure your app supports fast app switching. Fast app switching means that the app can go into the background for a short time without iOS terminating it. The AppConnect for iOS SDK requires that apps support this feature. Most apps support fast app switching.

    To ensure that your app supports fast app switching, in your app’s Info.plist, remove the UIApplicationExitsOnSuspend key if it is present.

    NOTE: Your app does not need to support any of the UIBackgroundModes, such as audio or voip

First-time use of SDK in your app

If you are adding the AppConnect for iOS SDK to your app for the first time, do the tasks in Getting started task list.

Task lists for upgrading the SDK in your app

To upgrade an app that uses a prior version of the AppConnect for iOS SDK to use SDK version 4.3.0, use the appropriate task list in the following table.

Table 1. Upgrade task list

SDK version from which you are upgrading

Upgrade task list

SDK 4.2.1
  • Replace the AppConnect.framework bundle in the project folder.
  • If you are using the AppConnectExtension.framework, replace the AppConnectExtension.framework bundle in the project folder.
  • Declare the alt-appconnectURL scheme in your app’s Info.plist as another allowed URL scheme.
    See Declare the AppConnect URL schemes as allowed.

SDK 4.2.0
  • Replace the AppConnect.framework bundle in the project folder.
  • If you are using the AppConnectExtension.framework, replace the AppConnectExtension.framework bundle in the project folder.
  • Declare the alt-appconnectURL scheme in your app’s Info.plist as another allowed URL scheme.
    See Declare the AppConnect URL schemes as allowed.

SDK 4.1.1
  • Replace the AppConnect.framework bundle in the project folder.
  • If you are using the AppConnectExtension.framework, replace the AppConnectExtension.framework bundle in the project folder.
  • Declare the alt-appconnectURL scheme in your app’s Info.plist as another allowed URL scheme.
    See Declare the AppConnect URL schemes as allowed.

SDK 4.1
  • Replace the AppConnect.framework bundle in the project folder.
  • If you are using the AppConnectExtension.framework, replace the AppConnectExtension.framework bundle in the project folder.
  • Declare the alt-appconnectURL scheme in your app’s Info.plist as another allowed URL scheme.
    See Declare the AppConnect URL schemes as allowed.

SDK 4.0
  • Replace the AppConnect.framework bundle in the project folder.
  • If you are using the AppConnectExtension.framework, replace the AppConnectExtension.framework bundle in the project folder.
  • Declare the alt-appconnectURL scheme in your app’s Info.plist as another allowed URL scheme.
    See Declare the AppConnect URL schemes as allowed.

SDK 3.1 through 3.5

  1. Remove the existing AppConnect.framework and AppConnectResources.bundle from your Xcode project.

  2. Remove the libProtocolsBuffer.a and libCrypto.a libraries from your Xcode project if you added them only for making your app an AppConnect app. However, if you use specific versions of these libraries for other reasons, or indirectly link to versions of these libraries, keep them in your project and make sure they are linked before the AppConnect.framework.

    The libCrypto.a that is part of the AppConnect.framework is FIPS compliant. Therefore, if your only reason for linking in your own libCrypto.a is to be FIPS compliant, you can remove it.

  3. Remove the following command from your Xcode project’s Other Linker Flags (in Linking under Build Setting:

    -force_load $(SRCROOT)/AppConnect.framework/AppConnect

  4. Make sure Other Linker Flags include -ObjC because the AppConnect.framework is an Objective-C framework.

  5. Navigate to AppConnect.framework in the top-level of the extracted AppConnect SDK directory.

  6. Drag and drop AppConnect.framework to Embedded Binaries in the General settings of your Xcode project’s target. When Xcode prompts you to choose options for adding the file, select Create groups.

  7. Navigate to AppConnectResources.bundle in the AppConnect.framework directory of the extracted AppConnect SDK directory.

  8. Drag and drop AppConnectResources.bundle to Copy Bundle Resources in the Build Phases settings of your Xcode project’s target. When Xcode prompts you to choose options for adding the file, select Create groups.

  9. Add a Run Script section to the Build Phases settings of your Xcode project’s target.

  10. Add post_embed_actions.sh, located in the top-level of the extracted AppConnect SDK directory, to the scripts to run. This script removes extra architectures from the AppConnect app’s binary. Removing desktop architectures is required before submitting your app to the Apple App Store.

  11. Make sure Enable Bitcode is set to No in Build Options in the Build Settings of your Xcode project’s target.

  12. Include the boolean key MI_AC_PROVIDE_SCREEN_BLUR set to YES in your app’s info.plist. For details, see Add AppConnect-related entries to your Info.plist.

  13. Include Privacy - Face ID Usage Description to your app’s info.plist, with a string value indicating the purpose of Face ID use. For example, add the value AppConnect. If you manually add this key, its name is NSFaceIDUsageDescription.

  14. Declare the alt-appconnectURL scheme in your app’s Info.plist as another allowed URL scheme.
    See Declare the AppConnect URL schemes as allowed.

SDK 2.4 through 3.0
  1. Do the upgrade steps for SDK 3.1 through 3.5.
  2. Recommended: If your app is a dual-mode app, modify the dual mode behavior to include +shouldStartAppConnect:. For details, see Developing Third-party Dual-mode Apps.
  3. Recommended: If your app enforced the Open In data loss prevention policy, note that the AppConnect library now enforces the policy. Make appropriate code modifications. For details, see Open In policy API details .

SDK 1.9.1 through 2.3.1
  1. Do the steps for SDK 2.4 through 3.0.
  2. Declare the AppConnect URL schemes as allowed

SDK 1.9.0 or earlier

Refer to the 3.5 version of this guide, available at MobileIron AppConnect 3.5 for iOS SDK App Developers Guide or contact MobileIron Technical Support.

Getting started task list

NOTE: If you have an app that already uses a prior version of the AppConnect for iOS SDK and want to upgrade the app to use the current SDK version, see Task lists for upgrading the SDK in your app.

If you are adding the AppConnect for iOS SDK to your app for the first time, do the following tasks:

  1. Add AppConnect files and settings to your Xcode project
  2. Add your own libcrypto.a, libProtocolBuffers.a, and libssl.a libraries if needed
  3. Register as a handler of the AppConnect URL scheme
  4. Declare the AppConnect URL schemes as allowed
  5. Add AppConnect-related entries to your Info.plist
  6. Use AppConnect’s UIApplication subclass
  7. Initialize the AppConnect library
  8. Wait for the AppConnect singleton to be ready
  9. Optional: Specify app permissions and configuration in a plist file.

Add AppConnect files and settings to your Xcode project

Do the following tasks to add AppConnect files and settings to your app’s Xcode project:

  1. Make sure Other Linker Flags include -ObjC because the AppConnect.framework is an Objective-C framework.

  2. Navigate to AppConnect.framework in the top-level of the extracted AppConnect SDK directory.

  3. Drag and drop AppConnect.framework to Embedded Binaries in the General settings of your Xcode project’s target.

    When Xcode prompts you to choose options for adding the file, select Create groups.

  4. Navigate to AppConnectResources.bundle in the AppConnect.framework directory of the extracted AppConnect SDK directory.

  5. Drag and drop AppConnectResources.bundle to Copy Bundle Resources in the Build Phases settings of your Xcode project’s target.

    When Xcode prompts you to choose options for adding the file, select Create groups.

  6. Add a Run Script section to the Build Phases settings of your Xcode project’s target.

  7. Add post_embed_actions.sh, located in the top-level of the extracted AppConnect SDK directory, to the scripts to run.

    This script removes extra architectures from the AppConnect app’s binary. Removing desktop architectures is required before submitting your app to the Apple App Store.

  8. Make sure Enable Bitcode is set to No in Build Options in the Build Settings of your Xcode project’s target.

Add your own libcrypto.a, libProtocolBuffers.a, and libssl.a libraries if needed

The AppConnect.framework includes:

  • the libcrypto.a library.

    The included libcrypto.a library is FIPS compliant.

  • the libProtocolBuffers.a library.

    The included libProtocolBuffers.a library is by Booyah, Inc.

  • the libssl.a library.

However, if you need specific versions of these libraries, you can add them to your Xcode project.

When you add one of these libraries to your Xcode project, make sure it is listed higher than AppConnect.framework in your Xcode project in the General tab under Linked Frameworks and Libraries.

Alternatively, you can make sure your version of one of these libraries is used by adding a -force_load command to the linker in Xcode. For example. in your Xcode project, in Build Settings, under Linking, in Other Linker Flags, add:

-force_load "$(PROJECT_DIR)/dependencies/openssl_fips_ios/lib/libcrypto.a"

Register as a handler of the AppConnect URL scheme

Your app must handle the AppConnect URL scheme. Mobile@Work, MobileIron Go, and MobileIron AppStation use this URL scheme to communicate with your app’s instance of the AppConnect library.

Register the AppConnect URL scheme by modifying the app’s Info.plist. Edit the key called URL types so that:

  • the sub-item URL identifier has the value of your app’s bundle identifier
  • the sub-item URL Schemes’ sub-item 0 has the value ac concatenated with your app’s bundle identifier

These key-value pairs are illustrated by the following excerpt from HelloAppConnect’s HelloAppConnect-Info.plist:

NOTE: If you are editing the Info.plist file directly, it should include the following: 
<key>CFBundleURLTypes</key>
<array>
   <dict>
      <key>CFBundleURLSchemes</key>
      <array>
         <string>ac$(PRODUCT_BUNDLE_IDENTIFIER)</string>
      </array>
   </dict>
</array>

Declare the AppConnect URL schemes as allowed

Declare the appconnect and the alt-appconnectURL schemes in your app’s Info.plist as allowed URL schemes. Your app’s instance of the AppConnect library:

  • uses the appconnect URL scheme to communicate with Mobile@Work or MobileIron Go.
  • uses the alt-appconnect URL scheme to communicate with MobileIron AppStation.

To allow the appconnect and alt-appconnect URL schemes, add a key called LSApplicationQueriesSchemes as shown in this example from HelloAppConnect’s HelloAppConnect-Info.plist:

Add AppConnect-related entries to your Info.plist

Enable screen blurring

The AppConnect library can automatically blur your app’s screen whenever it is not active. This security measure protects the app’s data from being captured in screenshots. The AppConnect library blurs the screen when
-applicationWillResignActive: is called and unblurs it when -applicationDidBecomeActive: is called.

To enable screen blurring, add the key MI_AC_PROVIDE_SCREEN_BLUR to your app’s Info.plist as a Boolean. Set the value to YES.

When you set the Info.plist key MI_AC_PROVIDE_SCREEN_BLUR to YES, the MobileIron server administrators can disable screen blurring by setting a key-value pair on the server for your app’s configuration. The server key is MI_AC_ENABLE_SCREEN_BLURRING with the value false.

NOTE: If you already implemented screen blurring in your app, remove that code and use the MI_AC_PROVIDE_SCREEN_BLUR plist key. Using the plist key ensures that all AppConnect apps behave consistently.

Allow Face ID

Include Privacy - Face ID Usage Description to your app’s info.plist, with a string value indicating the purpose of Face ID use. For example, add the value AppConnect. If you manually add this key, its name is NSFaceIDUsageDescription.

Server administrators can allow the use of Touch ID or Face ID instead of an AppConnect passcode. Therefore, this Info.plist entry is required on iOS 11 through the most recently released version as supported by MobileIron.

Use AppConnect’s UIApplication subclass

To use AppConnect’s UIApplication subclass:

  1. Open main.m for editing.

  2. Add the following line to your import statements:

    #import "AppConnect/AppConnect.h"

  3. Change the third argument of the call to UIApplicationMain() to
    kACUIApplicationClassName.

    The third argument, the principalClassName argument, is the UIApplication class or subclass for the app. For example, in the HelloAppConnect app provided with the AppConnect for iOS SDK, the statement that calls UIApplicationMain is:

        return UIApplicationMain(argc, argv, kACUIApplicationClassName,                     
                             NSStringFromClass([AppDelegate class]));
NOTE: If you use a subclass of UIApplication for your app, see Using your own UIApplication subclass.

Initialize the AppConnect library

To initialize the AppConnect library for your app to use:

  1. Open your AppDelegate source file and header file for editing.
  2. Add the following line to your import statements in your AppDelegate header file:
    #import "AppConnect/AppConnect.h"

  3. Create a class that implements the AppConnectDelegate protocol.

    Usually this class is also the AppDelegate for your app. For example, in AppDelegate.h in HelloAppConnect, the AppDelegate class implements the AppConnectDelegate protocol.

    @interface AppDelegate : UIResponder <UIApplicationDelegate, AppConnectDelegate>

    Some of the methods of the AppConnectDelegate protocol are optional. Implement only the optional methods that relate to your app’s functionality.

  4. Call the static method +initWithDelegate: of the AppConnect class.The method takes as a parameter an object of the class that implements the AppConnectDelegate protocol.

    For example, in HelloAppConnect, in the AppDelegate class implementation, the method -application:didFinishLaunchingWithOptions: calls +initWithDelegate: as follows:

    [AppConnect initWithDelegate:self];

    NOTE: If the class that implements the AppConnectDelegate protocol is not your AppDelegate, pass an instance of that class instead of self.

  5. Save the singleton instance of the AppConnect library.

    For example, in HelloAppConnect, the AppDelegate object saves the singleton instance in the appConnect property:

    [self setAppConnect:[AppConnect sharedInstance]];

  6. Call the AppConnect singleton’s method -startWithLaunchOptions:.

    The app must call this method from its AppDelegate’s method -application:didFinishLaunchingWithOptions:, and must pass along its launchOptions parameter value.

    For example, in HelloAppConnect:

    [self.appConnect startWithLaunchOptions:launchOptions];

    After this step, the AppConnect singleton is initializing. However, the app cannot yet use the singleton’s instance properties. The app can:

    • use the AppConnect class properties.
    • use the methods of the AppConnect singleton object.
    • register any NSURLProtocol subclasses that the app uses.

    If your app uses AppTunnel with HTTP/S tunneling, be sure this NSURLProtocol registration occurs after initializing the AppConnect library.

  7. If your application supports UIScene, call the method ‑sceneWillConnectToSessionWithOptions.

    The app must call the method from its UISceneDelegate's method ‑scene:willConnectToSession:options:, and must pass along the UIScene connection options as input parameter to the AppConnect instance method ‑sceneWillConnectToSessionWithOptions:.

    Example  

    @implementation MySceneDelegate

    - (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {

    [self.appConnect sceneWillConnectToSessionWithOptions:connectionOptions];

    }

    @end

  8. Indicate in the user interface that the app is initializing if the app requires the AppConnect singleton’s instance properties to determine what to do. For example, use an activity indicator (spinner). Remove the indication after the app is notified that the AppConnect singleton is ready.

    One reason this indication is important involves when to display sensitive data. Do not show any sensitive data until the AppConnect singleton is ready, because until that time, the app cannot determine whether it is authorized. Only an authorized app should show sensitive data.

Wait for the AppConnect singleton to be ready

The app cannot use the AppConnect singleton’s instance properties until the ready property on the AppConnect singleton is set to YES. It is set to YES when the callback method -appConnectIsReady: in your AppConnectDelegate protocol implementation is called. The app can now access the instance properties, such as authState and pasteboardPolicy, on the AppConnect singleton.

Before accessing any instance properties, use the isReady getter to make sure the properties are accessible.

For example, in HelloAppConnect, the -appConnectIsReady: callback method calls -updateLabels:. The
-updateLabels: method calls various methods that access the instance properties on the AppConnect singleton. Because other methods also call -updateLabels:, the method first checks the isReady property:

if ([self.appConnect isReady]) {
 
    // Call methods that access instance properties.
}	
else {
        authInfoText = @"Ready: NO (AppConnect is not ready yet)";
        policyInfoText = @"AppConnect is not ready yet";
        configInfoText = @"AppConnect is not ready yet";
}

For details about the -appConnectIsReady: callback method and the ready property, see AppConnect ready API details .

Optional: Specify app permissions and configuration in a plist file

If your app is an in-house app, you can specify default values for:

  • the data loss prevention policies, such as the Open In policy
  • the key-value pairs for your app-specific configuration

Specifically, you can provide a special plist file called AppConnect.plist as part of your in-house app that:

  • specifies whether your app should be allowed by default to copy to the iOS pasteboard, use document interaction (Open In and Open From), and print.
  • specifies app-specific configuration keys and default values.

These default values are used by the MobileIron server to make it easier for the server administrator to set up your app with the correct data loss prevention policies and app-specific configurations. Your app never reads the AppConnect.plist.

When you include the AppConnect.plist in your app:

  1. When an administrator uploads your in-house app to the MobileIron server, the server uses this plist file to automatically create server policies that contain your specified data loss prevention policies and app-specific configuration.

  2. The administrator can then edit these policies.

    For example:

    • If one of your app-specific configuration keys requires a URL of an enterprise server, the administrator provides that value.
    • If the administrator requires stricter data loss prevention policies than your app’s default values, the administrator changes the values.

  3. The administrator then applies these policies to the appropriate set of devices.

  4. When your app runs, it receives the data loss prevention policies and app-specific configuration by using the AppConnect for iOS APIs, described in AppConnect for iOS API.

    For example, to handle app-specific configurations, you use the config property (an NSDictionary object) and the callback method -appConnect:configChangedTo:

  5. If the administrator later changes the data loss prevention policies or app-specific configuration, your app receives the updates by using the AppConnect for iOS APIs.

An example of an AppConnect.plist file as viewed in Xcode looks like the following:

To set up an AppConnect.plist file:

  1. Create a plist file called AppConnect.plist.

  2. Place it in the root directory of your app.

  3. In the Root key of AppConnect.plist, place a key called bundleid with the type String, and set the value to the bundle ID of your app.

  4. In the Root key of AppConnect.plist, create two keys called policy and config, each with the type Dictionary.

  5. In the policy dictionary, create keys called openin, openinwhitelist, openfrom, openfromwhitelist,pasteboard, and print, each with the type String.

  6. Set these keys’ values as given in the following table:

    Table 2. AppConnect.plist keys and values

    Key

    Possible values and meanings

    openin

    • allow

    Document interaction is allowed with all other apps.

    • disable

    Document interaction is not allowed.

    • whitelist

    Only documents in the openinwhitelist list can open documents from your app.

    • appconnect

    Document interaction is allowed with all other AppConnect apps.

    This value results in the app receiving a whitelist in the Open In policy API. The whitelist contains the list of all currently authorized AppConnect apps. You do not enter an openinwhitelist key in the plist. See The openInPolicy and openInWhitelist properties .

    openinwhitelist

    Semi-colon separated list of the bundle IDs of the apps with which document interaction is allowed. This key is necessary when the openin key has the value whitelist.

    pasteboard

    • allow

    Pasteboard interaction is allowed with all other apps. That is, this option allows the device user to be able to copy content from your app to the iOS pasteboard. Then, any app can copy from the content from the pasteboard.

    • disable

    Pasteboard interaction is not allowed.

    • appconnect

    Pasteboard interaction is allowed only with other AppConnect apps. That is, this option allows the device user to be able to copy content from your app to the iOS pasteboard. Then, only other AppConnect apps can copy the content from the pasteboard.

    print

    • allow

    Printing is allowed.

    • disable

    Printing is not allowed.

  7. In the config dictionary, create keys as required for your app.

  8. Optionally, add values for the keys. The values must be String types.

    NOTE: The value $USERID$ in the example tells Core to substitute the device user’s user ID for the value. Other possible variables are $EMAIL$ and $PASSWORD$. Depending on the Core configuration, custom variables called $USER_CUSTOM1$ through $USER_CUSTOM4$ are sometimes available.

Using your own UIApplication subclass

If your app uses its own subclass of UIApplication, do the following:

  1. Derive your subclass from AppConnectUIApplication instead of UIApplication.

    You will need the following import statement:

    #import "AppConnect/AppConnectUIApplication.h"

  2. Change the third argument of the call to UIApplicationMain() to the name of your subclass of AppConnectUIApplication.

    The third argument, the principalClassName argument, is the UIApplication subclass for the app.

  3. When you override an UIApplication method in your subclass, always invoke the method implementation of the superclass AppConnectUIApplication at the end of your method.

    For example:

    [super sendEvent:event]

    If you do not invoke the superclass implementation, AppConnect features will not work in your app.