AirWatch iOS SDK implementation walkthrough

In this setup tutorial, we are using Xcode version 6.4 and iOS SDK version 5.4.1. 

The AirWatch Software Development Kid (SDK) is a set of tools allowing organizations to incorporate a host of features and functionality into their custom built iOS applications. The AirWatch SDK enhances the security and functionality of those applications and in turn helps save application development time and money. This document reviews the SDK implementation process as well as covers the options that are available and how they are configured. 

Please see the following diagram for an overview of the process:



Beginning with an Xcode project, launch Xcode and create a new project and select the option to start with a single page application. 



Add Required Frameworks

Add Required Xcode Frameworks

The SDK depends on the following frameworks to function properly. Please use the following steps to add necessary frameworks to your project:

1. Select the project in the Groups & Files pane in Xcode. 



2. Ensure the proper target is selected on the left side and click the Build Phases tab. 



3. Expand the Link Binary With Libraries section. 

4. Click the button at the bottom of the section to add the required frameworks. 



5. Select each one of the following frameworks and click Add.



Your libraries should resemble the following after adding them all:



Add Required Xcode Bundle Resources

The SDK depends on the following bundle resources to function properly, so add the necessary bundled to your project from the AirWatch SDK folder. Find some of these bundles inside the AWDSK.framework file structure. 

1. Still under Build Phases, navigate to Copy Bundle Resources.

2. Click on the + at the bottom of the section to copy in the bundle resources. 

3. Click on Add Other... and navigate to your AirWatch SDK mount. Make sure to always check Copy Items if Needed after selecting your bundle resources. 

Note: Add the AWKit.bundle to your project or the application may crash.


Progress made should resemble the following image:



Adding the AirWatch SDK Frameworks

The AirWatch frameworks are made available by running the provided AirWatchSDK.dmg file. 

1. Navigate back to the Link Binary with Libraries section and click the + button.

2. Select Add Other.

3. Navigate to the AirWatch SDK.dmg mount and select the AWSDK.framework file.

4. Click Add.

5. Be sure that the AWSDK.framework now appears in your Link Binary with Libraries section:



In the place where the AirWatch SDK is used, be sure to import the umbrella header. Add #import<AWSDK/AWSDKCore.h> to the top of the file.

Note: The AWController header is added in addition to the AWSDKCore header during initialization in the delegate file. For example, when initializing the SDK, please add #import<AWSDK/AWController.h> to your delegate file.


Adding Linker Flags

Since the AirWatch SDK uses Objective-C categories, a few linker flags must be passed to the linker to properly load them. The following steps help you configure your project:

1. Select the project or workspace in the Groups & Files pane

2. Select the target for the application

3. Select the Build Settings tab

4. Ensure the -ObjC flag is added in the Other Linker Flags entry. To do this, you can search for Other Linker Flags in the search box to the right of the Build Settings section. 



Valid Architectures

The SDK currently supports the following architectures:

  • ARMv7
  • ARMv7S
  • ARM64

In order to ensure these are added to your environment, search for Valid Architectures in the same search field as above. Note: Ensure not to compile the i386 architecture/simulator because the SDK only supports real physical devices. 




Call Back Scheme Registration

In order to receive a call back from the AirWatch Agent, your application will need to expose a custom scheme in the info.plist.

1. Navigate to Supporting Files in Xcode

2. Select the file <YourAppName>-Info.plist

3. Navigate to the URL Types section. If it does not exist, add it at the Information.PropertyList root node of the .plist

4. Expand the Item 0 entry to add an entry for URL Schemes

5. Set the next Item 0 under URL Schemes to the desired callback scheme. 



The callback scheme will then need to match what is set within your didFinishLaunchingWithOptions in your AppDelegate:



An example of the info.plist from the sample above is as follows: 




Compiling with Xcode 7

If you use Xcode 7 to compile your SDK application, take the following additional steps to ensure proper functionality for your SDK application. 

1. Add an array key named LSApplicationQueriesSchemes to the info.plist

2. Add the bundle identifier of the AirWatch Agent or Container application to the array. The schemes for the Agent and Container are as follows:

- airwatch

- workspace

3. Navigate to your Xcode build settings and set Enable Bitcode to No


Configure the Server Connections (Initial Setup)

In order to start using the AirWatch SDK, you must set an initial configuration so that the SDK receives the AirWatch Device Services URL. This configuration allows the SDK to communicate with the server for every transaction that required interaction with the AirWatch Admin Console. 


Initializing the SDK

Before you can use the SDK, you must initialize it. The AWController class is the main component responsible for initializing the SDK. In addition, it automatically handles and implements certain core SDK functionalities to improve ease of integration for developers, such as the following functions:

  • Passcode Mode
  • Single Sign On (SSO)
  • SSID Filtering
  • Proxy and Tunneling

Note: Calling start in AWController automatically sets up the proxy to redirect traffic. However, you must wait until the initial CheckDoneWithServer callback is received before any network traffic redirects. Wait until the SDK finishes settings up before making any network calls that need to go through your proxy. The following example demonstrates how to initialize the SDK. 


Import the <AWSDK/AWController.h> header file:

 #import <AWSDK/AWController.h>



Associate the AWControllerDelegate to your app delegate (also in AppDelegage.h):

@interface AppDelegate : UIResponder <UIApplicationDelegate,AWSDKDelegate>



Inside your AppDelegate.m, implement the following in your didFinishLaunchingWithOptions:

  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Configure the Controller by:

AWController *controller = [AWController clientInstance];

// 1) defining the callback scheme so the app can get called back, controller.callbackScheme=@"UrlScheme";

// 2) set the delegate to know when the initialization has been completed. controller.delegate=self;
return YES;



Start the SDK initialization inside the applicationDidBecomeActive delegate method:

-   (void)applicationDidBecomeActive:(UIApplication *)application {
[[AWController clientInstance] start];



Note: It is best not to call the start method above in didFinishLaunchingWithOptions. The SDK may display modal view controllers that rely on a reference view controller.  In certain cases when you use a storyboard, the view controllers have not net been generated at the time didFinishLaunchingWithOptions is called. To voice any unstable behavior with the app, call [[AWController clientInstance] start] inside applicationDidBecomeActive instead. 


Next, implement the code to handle the callback from the AirWatch Agent or AirWatch Container app. This method will need to be added separately, as it is not an iOS callback method that's already in your AppDelegate.m. 


- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *) sourceApplication annotation:(id)annotation {
return [[AWController clientInstance] handleOpenURL:url fromApplication:sourceApplication];



Finally, implement the remaining delegate methods:

-   (void)initialCheckDoneWithError: (NSError *)error



This delegate method is invoked when the SDK initializes. This method is always called after the SDK passes through the initialization flow. If the initialization is successful then the error object is nil. If the initialization fails, then the error object contains the reason code for why it fails. 


- (void)receivedProfiles:(NSArray *)profiles



This delegate method is invoked when settings of an SDK profile assigned to this application update on the AirWatch Admin Console. It notifies the app that new settings are available. The profiles array contains the list of AWProfile objects that contain configuration payloads. 


- (void)unlock



This delegate method is invoked immediately after you initiate a new SSO session by inputting the correct password/passcode.



- (void)lock



This method is invoked when the SSO session has expired and the SDK passcode input view is displayed. It is intended for use as an indicator of when a user should no longer have to access the app. This lock allows the developer to implement the necessary logic to take the proper action for when the app is locked.



- (void)wipe



This method is invoked when the SDK identifies that the device has been wiped or unnerved from the AirWatch Admin Console. This method is also invoked when a user reaches the limit of failed passcode attempts defined in the SDK profile. 

Note: The AirWatch SDK does not take any action other than invoking this method. The application developer must implement the necessary local app wipe logic. 



- (void)stopNetworkActivity



This method is invoked when the device connects to an SSID that is blacklisted in the SDK profile.



- (void)resumeNetworkActivity



This method is invoked when the device connects to a valid SSID after network activity is already stopped. 



Finishing Up

The basic SDK functionality has been added to the project. Currently, the SDK is not doing much of anything in your application and additional source code will need to be added to implement the desired use of the SDK through the separate SDK modules. Further functionality can be found by implementing the Beacon, DataSampler, or the MDM status sampler using the SDK guide. To recap, in order to use the SDK, the application must be pushed as a managed app from the AirWatch console. 

Have more questions? Submit a request


Article is closed for comments.