Use this document to install the VMware AirWatch SDK Plugin for Xamarin. The plugin helps enterprise app developers add enterprise- grade security, conditional access, and compliance capabilities to mobile applications.

For a PDF version of this document, see https://resources.air-watch.com/view/5xvh5zt2lnkmmrc3b2k5/en.

Initialization

Initialization of the SDK includes many features that have corresponding configurations in the AirWatch Console.

  • Application level passcode
  • App level tunneling using ModernHTTPClient
  • Integrated authentication and single sign on (SSO)
  • Data Loss Prevention
    • Disable screenshots (Android only)
    • Restrict open-in for documents, web links, and email to only approved applications
    • Restrict copy and paste with an SDK-provided flag value
  • Restrict access to the application when a device is offline
  • Brand splash screens when the application is launched on devices
  • Custom Settings

Supported Components

This plugin works with the listed versions.

iOS

  • iOS 9.0+
  • Xamarin Studio

    If you have Visual Studio with the Xamarin plug-in, this works. However, this document does not outline that method.

  • AirWatch-enrolled iOS test device
  • The AirWatchSDK.dll from the Xamarin Component Store
  • An iOS application built with Xamarin to integrate with the Airwatch SDK

    If you do not have an application, you can create a new application in Xamarin Studio and integrate the SDK into that.

Android

  • Xamarin Studio or Visual Studio with the Xamarin plugin
  • The AirWatch SDK binaries from the Xamarin Component Store
  • An Android test device running Ice Cream Sandwich+
  • Xamarin Android application to integrate with the Airwatch SDK targeting Android 4.1+ / API Level 14-25
  • The AirWatch Agent v7.0+ for Android from the Google Playstore
  • A whitelisted release/debug signing key for signing the Xamarin-built Android application

iOS Overview

Integrate the AirWatch SDK with your Xamarin project.

Add Applications to the AirWatch Console

Export your application as a signed IPA and then upload it to the console as an internal application. You must assign an SDK profile to the application. Ask your AirWatch Administrator for details. The process is explained in the VMware AirWatch Online Help. See https://my.air-watch.com/help/9.2/en/Content/CoreGuides/MAM/T/ConfigInternalAppsLocal.htm.

Add Required SDK DLL to Project

Get the VMware AirWatch SDK from the Xamarin Component Store. Add the AirWatch SDK DLL to your Xamarin project. This process enables the Xamarin IPA file to recognize and apply the AirWatch SDK functionality.

  1. Open Xamarin Studio.
  2. Right-click References and choose Edit References.
  3. Select the .Net Assembly tab and then choose Browse.
  4. Select the AirWatchSDK.dll file from your file system.
  5. Enable the Assembly check box, if it isn't already, and select OK.

Enable Communication Between the AirWatch Agent and the Xamarin IPA File

The application must communicate with the AirWatch Agent for iOS. The application must register itself with the AirWatch environment. This action allows it to receive the SDK profiles assigned to it. Add a custom scheme in the application's PLIST file. Use the scheme in the callback scheme registration.

sdkController.CallbackScheme = "mysamplescheme"; //defined in Info.plist

Add Callback Scheme Registration

  1. Double-click the Info.plist file in your Xamarin project.
  2. Select the Advanced tab.
  3. In the URL Types section, choose Add URL Type.
  4. Set the values of Identifier and URL Schemes to the desired callback scheme.
  5. Set the Role to Editor.
  6. Save the file.

Add SDK App Query Scheme

The scheme for Workspace ONE is awws1enroll.

  1. Double-click the Info.plist file in your Xamarin project.
  2. Select the Source tab, and choose Add new entry.
  3. Select the green "PLUS" in the selected row.
  4. Double-click Custom Property and change it to LSApplicationQueriesSchemes.
  5. Change the Type from String to Array.
  6. Within the Array, select Add new entry.
  7. Select the green "PLUS" in the selected row.
  8. Double-click the Value column and set the value to airwatch.
  9. Add another entry under LSApplicationQueriesSchemes for workspace.
  10. Save the file.

Add an App Delegate to the Xamarin Project

To complete the integration of Xamarin and the AirWatch SDK, use a custom App Delegate. Create a class to act as an AWSDKDelegate, define the callback scheme within the class, and set the class to recognize when initialization is complete.

  1. Create a class to act as an AWSDKDelegate and to receive SDK callbacks.

    using Foundation;
                            using System.Diagnostics;
                            using System;
                            using AirWatchSDK;
                            
                            namespace sdkSampleApp
                            {
                            public class AirWatchSDKManager: AWSDKDelegate
                            {           
                            private static AirWatchSDKManager instance;
                            private static string LogCategory = "AirWatchSDK";
                            
                            // private, use the Instance below
                            private AirWatchSDKManager ()
                            {
                            }
                            
                            // singleton
                            public static AirWatchSDKManager Instance {
                            get {
                            if (instance == null) {
                            instance = new AirWatchSDKManager ();
                            }
                            return instance;
                            }
                            }
                            
                            // Below are all the protocol methods defined in AWSDKDelegate
                            // Add customization here for SDK results
                            
                            override public void InitialCheckDoneWithError (NSError error)
                            {
                            // Add any SDK Customization here
                            string message = String.Format ("InitialCheckDoneWithError received {0}, SDK initialized
                            if no error", error);
                            Debug.WriteLine (message, LogCategory);
                            }
                            
                            override public void ReceivedProfiles (AWProfile[] profiles)
                            {
                            // Add any SDK Customization here
                            string message = String.Format ("ReceivedProfiles received {0}", profiles);
                            Debug.WriteLine (message, LogCategory);
                            }
                            
                            override public void Wipe ()
                            {
                            // Add any SDK Customization here
                            Debug.WriteLine ("Wipe command received", LogCategory);
                            }
                            
                            override public void Lock ()
                            {
                            // Add any SDK Customization here
                            Debug.WriteLine ("Lock command received", LogCategory);
                            }
                            
                            override public void Unlock ()
                            {
                            // Add any SDK Customization here
                            Debug.WriteLine ("Unlock command received", LogCategory);
                            }
                            
                            public override void StopNetworkActivity(AWNetworkActivityStatus status)
                            {
                            // Add any SDK Customization here
                            Debug.WriteLine("StopNetworkActivity received", LogCategory);
                            }
                            
                            override public void ResumeNetworkActivity ()
                            {
                            // Add any SDK Customization here
                            Debug.WriteLine ("ResumeNetworkActivity received", LogCategory);
                            }
                            }
                            }
                            
                            
                            
                         
  2. Add the listed functionality to the AppDelegate.cs.

    using System;
                            using ObjCRuntime;
                            using System.Diagnostics;
                            using AirWatchSDK;
                            ...
                            public override bool FinishedLaunching (UIApplication application, NSDictionary launchOptions)
                            {
                            if (Runtime.Arch == Arch.SIMULATOR) {
                            Debug.WriteLine ("Running in Simulator, skipping initialization of the AirWatch SDK!");
                            return true;
                            } else {
                            Debug.WriteLine ("Running on Device, beginning initialization of the AirWatch SDK.");
                            
                            // Configure the Controller by:
                            var sdkController = AWController.ClientInstance ();
                            // 1) defining the callback scheme so the app can get called back,
                            sdkController.CallbackScheme = "mysamplescheme"; // defined in Info.plist
                            // 2) set the delegate to know when the initialization has been completed.
                            sdkController.Delegate = AirWatchSDKManager.Instance;
                            return true;
                            }
                            }
                            
                            public override void OnActivated (UIApplication application)
                            {
                            AWController.ClientInstance ().Start ();
                            }
                            
                            public override bool HandleOpenURL (UIApplication application, NSUrl url)
                            {
                            return AWController.ClientInstance ().HandleOpenURL (url, "");
                            }
                            
                            
                            
                         

    If you are using Xamarin Forms on iOS, you need to add this to your AppDelegate, too. This exposes the UIWindow that is part of the iOS AppDelegate but is hidden in Xamarin.Forms.Platform.iOS.FormsApplicationDelegate.

    [Export("window")]
                            public UIWindow GetWindow()
                            {
                            return UIApplication.SharedApplication.Windows[0];
                            }
                            
                            
                            
                         

ModernHTTPClient Integration for App Level Tunneling Functionality

Use ModernHTTPClient to add tunneling functionality.

Libraries

    using ModernHttpClient;
                  using System.Net.Http;
                  
                  
                  
               

Request and Response Format

Note:

See the sample application for an alternate tunneling method.

    var uri = new Uri("http://www.xyz.com"); //where xyz is internal url or the url
                  which needs to go via tunnel
                  var httpClient = new HttpClient(new NativeMessageHandler());
                  HttpResponseMessage response = await httpClient.GetAsync(uri);
                  
                  
                  
               

SDK Callbacks

  • override public void InitialCheckDoneWithError(NSError error): This is the first expected callback from SDK after initialization. If there is no error, then the SDK is successfully initialized and the user is authenticated.
  • override public void ReceivedProfiles(AWProfile[] profiles): Sent when the device receives the SDK or application profiles.
  • override public void Wipe(): Sent when the device receives a wipe command from the console or is wiped from any other applications.
  • override public void Lock(): Sent when the application is locked. The SDK shows the authentication screen when the system processes the lock action.
  • override public void unlock(): Sent when the application is being unlocked.
  • public override void StopNetworkActivity(AWNetworkActivityStatus status): Sent when the application should stop all the network activities due to violations of any settings in the console.
  • override public void ResumeNetworkActivity(): Sent when the application can resume network activities.

Functions

  • allowCopyPaste(): Returns a Boolean value that identifies if the copy paste operation is allowed between managed applications. Configure this function in the Data Loss Prevention (DLP) settings.
  • restrictDocumentToApps(): Returns a Boolean value that signifies if document-opening is allowed in specific applications. If allowed, then you can obtain a list of allowed applications from allowedApplicationsList().
  • allowedApplicationsList(): Returns a NSArray containing list of allowed applications for document opening when restrictDocumentToApps is enabled. Configure this function in the DLP settings.
  • allowCamera(): Returns a Boolean value that signifies if camera access is allowed or not. Configure this function in the DLP settings.
  • customSettings(): Returns a string containing Custom settings. Set this function in the AirWatch Console Settings And Policies> Settings > Custom Settings. If this is a custom profile, set the function while creating a custom profile.
  • allowIntegratedAuthentication(): Returns a Boolean that signifies if integrated authentication is allowed or not.
  • allowedSitesList(): Returns the list of allowed sites for integrated authentication. Configure this function in the Integrated Authentication settings.
  • openDocumentFromUrl(NSUrl url, UIView view): Opens documents using AWDocumentInteractionController and provides the url and view.
  • openDocumentFromFile(string filename, string fileExt): Opens documents using AWDocumentInteractionController and gives the file name and extension.
  • DLPEnabled(): Returns a Boolean value that identifies if DLP is enabled in the AirWatch Console.

Troubleshooting Tip for SSO

Ensure that Single Sign On (SSO) is enabled in the AirWatch Console and that an authentiation type is configured in the AirWatch Console. The application does not display an SSO passcode if these settings are not configured in the console. Ask your AirWatch Administrator to enable SSO and to select an authentication type in the console in Groups & Settings > All Settings > Settings and Policies > Security Policies.

Android Overview

This document describes how to integrate the VMware AirWatch SDK for Android components into an existing Xamarin Android application.

Integrate the AirWatch SDK

Integrate the AirWatch SDK into your Android application built with Xamarin.

Enable Multi-Dexing and Add Binaries and Dependencies

While integrating the AirWatch SDK, the application method count can exceed 64k due to library dependencies. To prevent issues, enable multi-dexing.

  1. Enable the Multi-Dex option for the application in Xamarin.
  2. Add the five AirWatch SDK for Android binaries (DLLs) downloaded through the Xamarin Component Store as References to the application.
    • AWClientSDKBindings
    • AWMixPanelBindings
    • AWSQLCipherBindings
    • AWFrameworkBindings
    • AWNetworkLibraryBindings
  3. Add the dependency NuGet packages from the NuGet Package Manager as References to the application.
    • Xamarin.Android.Support.v13 version 25.3.1
    • Xamarin.Android.Support.v7.AppCompat version 25.3.1
    • Xamarin.Android.Support.v7.CardView version 25.3.1
    • Xamarin.Android.Support.v7.RecyclerView version 25.3.1
    • Xamarin.Android.Support.Design version 25.3.1
    • Xamarin.Android.Support.v14.Preference version 25.3.1
    • Xamarin.GooglePlayServices.SafetyNet version 32.961.0
    • Square.OkHttp3 version 3.5.0
  4. Initialize the AirWatch SDK.

Initialize the AirWatch SDK

  1. Extend the application class to the AWApplication class. Override the MainActivityIntent to return the application's main landing activity. Move the application's onCreate() business logic to onPostCreate().

    namespace XamarinAndroidSampleApp.Landing
                            {
                            [Application(Label = "@string/app_name", Icon = "@drawable/AppLogo", Theme = "@style/AppTheme")]
                            public class SampleApplication : AWApplication
                            {
                            public SampleApplication(IntPtr handle, JniHandleOwnership ownerShip)
                            : base(handle, ownerShip)
                            {
                            }
                            
                            public override Intent MainActivityIntent
                            {
                            get
                            {
                            var intent = new Intent(ApplicationContext, typeof(MainActivity)); // MainActivity
                            is application's main landing activity
                            return intent;
                            }
                            }
                            
                            public override Intent MainLauncherIntent
                            {
                            get
                            {
                            var intent = new Intent(ApplicationContext, typeof(GatewaySplashActivity));
                            return intent;
                            }
                            }
                            
                            public override bool MagCertificateEnable
                            {
                            get
                            {
                            return true; // to fetch mag certificate during initial setup
                            }
                            }
                            
                            protected override bool IsInputLogoBrandable
                            {
                            get
                            {
                            return true; // to brand application logo
                            }
                            }
                            
                            
                            public override void OnPostCreate()
                            {
                            base.OnPostCreate();
                            // App specific code here
                            }
                            }
                            } 
                            
                            
                            
                         
  2. Add 'AirWatchSDKIntentService' by setting the name as [AppPackageName].AirWatchSDKIntentService.

  3. Set GatewaySplashActivity as your main launching activity.

  4. Add 'AirWatchSDKBroadcastReceiver' broadcast receiver declarations in the manifest file.

    <application android:name="SampleApplication" android:theme="@style/AppTheme" tools:replace="android:label">
                            <activity android:name="com.airwatch.gateway.ui.GatewaySplashActivity" android:label="@string/app_name">
                            <intent-filter>
                            <action android:name="android.intent.action.MAIN" />
                            <category android:name="android.intent.category.LAUNCHER" />
                            </intent-filter>
                            </activity>
                            <activity android:name=".MainActivity" android:label="@string/app_name" />
                            <receiver android:name="com.airwatch.sdk.AirWatchSDKBroadcastReceiver" android:permission="com.airwatch.sdk.BROADCAST">
                            <intent-filter>
                            <action android:name="com.airwatch.xamarinsampleapp.airwatchsdk.BROADCAST" />
                            </intent-filter>
                            <intent-filter>
                            <action android:name="android.intent.action.PACKAGE_ADDED" />
                            <action android:name="android.intent.action.PACKAGE_REMOVED" />
                            <action android:name="android.intent.action.PACKAGE_REPLACED" />
                            <action android:name="android.intent.action.PACKAGE_CHANGED" />
                            <action android:name="android.intent.action.PACKAGE_RESTARTED" />
                            <data android:scheme="package" />
                            </intent-filter>
                            </receiver>
                            </application>
                            
                            
                            
                         
  5. For authentication, timeout, and data loss prevention features, all the application activities extend from Com.Airwatch.Gateway.UI.GatewayBaseActivity. This process enables the application to handle the lifecycle and to manage the state of the AirWatch SDK.

Features

  • Application level branding, authentication, timeout behavior, and offline access are enforced by integrating and extending the AirWatch base activity.
  • For application level tunneling, use normal HTTP clients or Android WebView. Android WebView refers to the Tunnel URLs set in the AirWatch Console. Review the sample app for code.
  • For integrated authentication, the application uses AirWatch wrapped HTTP clients or AWWebView for Basic, NTLM, or client certificate based authentication. Review the sample app for code.
  • For data loss prevention
    • Restricting screenshot actions is enforced when your activity extends GatewayBaseActivity.
    • To restrict copy-paste actions, the application uses AirWatch wrapped textviews like AWEditText, AWTextView, and AWWebView.
    • To restrict open-in for documents, weblinks, and email, use UriOpenerFactory.Instance.OpenUri(context, uri) and UriOpenerFactory.Instance.OpenUri(context, filepath) as shown in the sample app.
  • For custom settings, use the SDKManager API. You can use any SDKManager API.

    try
                            {
                            // Below call will return SDKManager instance readily 
                            // as it is already initialised as part of Login flow.
                            var sdkmanager = SDKManager.Init(this);
                            textView.Text = sdkmanager.CustomSettings;
                            } catch (AirWatchSDKException e)
                            {
                            // exception while using SDKManager API
                            }
                            
                            
                            
                         

Whitelist Signing Key

Before you can use the AirWatch SDK for Android, ensure your application's signing key is whitelisted with your AirWatch Console. When your SDK-integrated application starts up, the SDK checks the signing public key. It compares it against the list of whitelisted applications to determine if your application is trusted.

AirWatch allows whitelisting for both applications deployed internally or deployed through a public app store.

Internally Deployed Applications

  1. After building the application APK, sign it using your own specific app signing key.
  2. Upload the signed APK file to the AirWatch Console. The AirWatch Console extracts the application's public signing key and adds it to the whitelisted apps list. You must assign an SDK profile to the application. Ask your AirWatch Administrator for details. The process is explained in the VMware AirWatch Online Help. See https://my.air-watch.com/help/9.2/en/Content/CoreGuides/MAM/T/ConfigInternalAppsLocal.htm.

Publicly Deployed Applications

For applications that are deployed publicly through an app store, send the public signing key of the application to AirWatch for whitelisting.

Note:

Contact your VMware AirWatch representative for help with whitelisting the public signing key.

Questions and Feedback

Let us know if you have any questions or feedback by emailing us at https://support.air-watch.com/.

For further details about the AirWatch SDK, go to https://my.air-watch.com/help/9.2/en/Content/Online_Help_Topics/Overview_Topics/DeveloperDocs.htm.